ICADLL/NT Manual

ICADLL/NT Manual
CALIBRE
I2C Communications Adapter
Windows NT® Driver Manual
ICADLL/NT
Issue 2.4
15/07/1999
 Calibre UK Ltd 1999
CALIBRE
Welcome to the Calibre I2C for Windows NT 4.0 driver. This driver is designed to users to run
I2C Bus operations via the Calibre I2C adapter (ICA90 or ICA93).
Please note that in this manual sometimes refers to the I2C Communications Adapter User
Manual provided with your adapter. It will prove helpful if you have this to hand.
If you have any queries relating to this or any other I2C product supplied by Calibre please visit
our web site www.calibreuk.com.
For technical support please e-mail techsupport@calibreuk.com or send your queries by fax to
(44) 1274 730960, for the attention of our I2C Technical Support Department.
COPYRIGHT
This document and the software described within it are copyrighted with all rights reserved.
Under copyright laws, neither the documentation nor the software may be copied, photocopied,
reproduced, translated, or reduced to electronic medium or machine readable form, in whole or in
part, without prior written consent of Calibre UK Ltd ("Calibre"). Failure to comply with this condition
may result in prosecution.
Calibre does not warrant that this software package will function properly in every
hardware/software environment. For example, the software may not work in combination with
modified versions of the operating system or with certain network adapter drivers.
Although Calibre has tested the software and reviewed the documentation, CALIBRE MAKES
NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO
THIS SOFTWARE OR DOCUMENTATION, THEIR QUALITY, PERFORMANCE,
MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. THIS SOFTWARE AND
DOCUMENTATION ARE LICENSED 'AS IS', AND YOU, THE LICENSEE, BY MAKING USE
THEREOF, ARE ASSUMING THE ENTIRE RISK AS TO THEIR QUALITY AND PERFORMANCE.
IN NO EVENT WILL CALIBRE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL,
INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO
USE THE SOFTWARE OR DOCUMENTATION, even if advised of the possibility of such damages.
In particular, and without prejudice to the generality of the foregoing, Calibre has no liability for any
programs or data stored or used with Calibre software, including costs of recovering such programs or
data.
Copyright
(c) 1999
Calibre UK Ltd
Cornwall House, Cornwall Terrace
Bradford, BD8 7JS. UK.
E-mail: sales@calibreuk.com
Web site www.calibreuk.com
All World-wide Rights Reserved
Issue 2.4
15/07/1999
All trade marks acknowledged
Calibre operates a policy of continued product improvement, therefore specifications are subject to
change without notice as products are updated or revised.
E&OE.
Issue 2.4
15/07/99
Page i
CALIBRE
Contents
INTRODUCTION
1.1.
General Introduction
1.2.
System Requirements
1.3. .
Configuring the Adapter
1.4.
Installing the Adapter
INSTALLING THE DRIVER INTO YOUR SYSTEM
2.1.
File Location
2.2.
Registering the Driver Windows NT V4.0
LIBRARIES FOR PROGRAMMING IN MICROSOFT WINDOWS NT ENVIRONMENTS
3.1.
Windows LIB/DLL Functions
3.1.1.
Files
3.2.
Introduction
3.3.
C++ functions - Function Prototypes
3.4.
VB5.0 functions - Function Declarations
3.5.
Function Description
3.5.1.
setup
3.5.2.
sendaddress
3.5.3.
writebyte
3.5.4.
readbyte
3.5.5.
sendstop
3.5.6.
restart
3.5.7.
getstatus
3.5.8.
recover
3.5.9.
slavelastbyte
THE MOST COMMONLY ASKED I2C QUESTIONS
4.1.
General Questions
4.2.
DOS Software Questions
4.3.
WINDOWS 95 and NT Questions
Issue 2.4
15/07/99
1
1
1
1
1
2
2
2
3
3
3
3
3
3
4
4
4
5
5
6
6
7
7
7
8
8
8
8
Page ii
CALIBRE
INTRODUCTION
1.1.
General Introduction
This document details the installation and use of the I2C communications adapter (ICA) Windows
NT® driver.
This driver is suitable for both the ICA90 and the ICA93.
1.2.
System Requirements
This driver is suitable for Windows NT® 4.0.
1.3..
Configuring the Adapter
NOTE:
MANY COMPONENTS ON THE ADAPTER CARD ARE STATIC SENSITIVE. OBSERVE
NORMAL STATIC SENSITIVE PRECAUTIONS WHEN HANDLING THE CARD!
See the adapter manual for details on how to configure the adapter.
1.4.
Installing the Adapter
Install the adapter into the PC in accordance with its manual.
Issue 2.4
15/07/99
Page 1
CALIBRE
INSTALLING THE DRIVER INTO YOUR SYSTEM
2.1.
File Location
Unlock the files in accordance with the instructions provided with the license.
Copy the files as follows:1)Copy the WinRT.SYS file to the \WINNT\SYSTEM32\DRIVERS
2)Copy the .LIB into your compilers \lib
3)Copy the .DLL into \WINNT\SYSTEM
4)Copy the .H file into your project directory
2.2.
Registering the Driver Windows NT V4.0
From the DOS prompt run the NTReg.exe program when prompted enter the offset of the adapter
from 310H for example
Hardware address = 310H enter 0
Hardware address = 312H enter 2
"
"
Hardware address = 31EH enter E
Hardware address = 31FH enter F
The address offset entered must match the base address link setting of the adapter.
Then enter the IRQ required (ensure that this IRQ is not used by any other part of your system). Most
applications use the adapter in a polled mode (i.e. interrupts are not used) in this case select 0 - IRQ
disabled.
Guidance relating to the registry can be found on www.calibreuk.com.
Issue 2.4
15/07/99
Page 2
CALIBRE
LIBRARIES FOR PROGRAMMING IN MICROSOFT WINDOWS NT ENVIRONMENTS
3.1.
Windows LIB/DLL Functions
3.1.1.
Files
NTREG.EXE
WINRT.SYS
Driver registration application (for use with NT V4.0)
BlueWater Systems WinRT® driver
\cpp\CALI2C32.H
\cpp\I2C_NT.LIB
\cpp\I2C_NT.DLL
\vb5\CALI2C.BAS
"C" function prototypes
I2C "C" library
I2C dynamic link library
"Visual Basic 5.0 declarations"
\vb\I2CVB_NT.DLL
\vb\I2CVB_NT.LIB
"Dynamic link library for Visual Basic 5.0"
"Library for Visual Basic 5.0"
3.2.
Introduction
Each utility is documented in a standard format which lists its name, usage, function and effect on the
adapter is given. The adapter should be setup prior to any data transfer.
3.3.
C++ functions - Function Prototypes
To ensure the prototypes are added correctly copy the file CALI2C32.H into the directory containing
your project and add the line:
#include "CALI2C32.H"
The following functions are implemented in the windows libraries:extern __declspec(dllimport) int setup (int, int, int, int);
extern __declspec(dllimport) int sendaddress (int, int );
extern __declspec(dllimport) int restart (int, int);
extern __declspec(dllimport) int getstatus (void);
extern __declspec(dllimport) int writebyte (int );
extern __declspec(dllimport) int readbyte (int );
extern __declspec(dllimport) int sendstop (void);
extern __declspec(dllimport) int recover (void);
extern __declspec(dllimport) int slavelastbyte (void);
extern __declspec(dllimport) int dllversion (void);
3.4.
VB5.0 functions - Function Declarations
To ensure the prototypes are added correctly copy the file CALI2C.BAS into the directory containing
your project and add the file to your project line:
The following functions are implemented in the windows libraries:Public Declare Function setup Lib "i2cvb_nt.dll" (ByVal baseaddress As Integer, ByVal ownaddress As
Integer, ByVal sclk As Integer, ByVal statuswait As Integer) As Integer
Public Declare Function sendaddress Lib "i2cvb_nt.dll" (ByVal slaveaddress As Integer, ByVal setnack
As Integer) As Integer
Public Declare Function restart Lib "i2cvb_nt.dll" (ByVal slaveaddress As Integer, ByVal setnack As
Integer) As Integer
Public Declare Function writebyte Lib "i2cvb_nt" (ByVal wrdata As Integer) As Integer
Public Declare Function readbyte Lib "2cvb_nt.dll" (ByVal setnack As Integer) As Integer
Public Declare Function sendstop Lib "i2cvb_nt.dll" () As Integer
Public Declare Function getstatus Lib "2cvb_nt.dll" () As Integer
Public Declare Function recover Lib "i2cvb_nt.dll" () As Integer
Public Declare Function slavelastbyte Lib "i2cvb_nt.dll" () As Integer
Public Declare Function dllversion Lib "i2cvb_nt.dll" () As Integer
Issue 2.4
15/07/99
Page 3
CALIBRE
3.5.
Function Description
3.5.1.
setup
Function specification
int setup(int baseaddress, int ownaddress, int sclk, int statuswait)
Parameters are:
int baseaddress
This has no function and any value may be passed to setup, The
baseaddress has been retained to enable applications written for Windows
3.x to be ported with a minimum of changes.
int ownaddress
This is the I2C address to which the adapter is to respond in slave mode. This
forms the upper 7 bits of the 8 bit address, the lowest bit being the read(1) or
write(0) bit. This means that if ownaddress = 57H the card will respond to a
write address of AEH and a read address of AFH.
int sclk
This is the clock rate (bit rate for the I2C serial bus) when operating as a
master.
Value of sclk
Approximate SCL-kHz
0
90
1
45
2
11
3
1.5
int statuswait
This is a period of time (in micro seconds) to wait for the required bus status.
If this time-out expires the I2C functions will exit returning an error code.
Parameters returned
If the software fails to find the driver error code 9001H is returned otherwise
the status is returned.
Prerequisites
None.
Functional description
This function characterises the PC and initialises adapter ready for I2C
transfers.
3.5.2.
sendaddress
Function specification
Int sendaddress(int slaveaddress, int setnack)
Parameters are:
int slaveaddress
This is the address to be accessed via the I2C, e.g. A0H.
int setnack
This controls whether the adapter transmits an acknowledge down the I2C
bus on reception of a byte. The last byte received during a transfer must not
be acknowledged, in all other cases acknowledge must be enabled. If
setnack = 0 then acknowledge is enabled, if setnack = 1 then acknowledge is
disabled. Therefore, if a read (odd numbered) address is being sent AND only
1 Byte is to be read, setnack should be set to = 1; in all other cases it must be
clear = 0.
Parameters returned
int ErrCode.
If the software fails to open a handle to the driver 0x9000 is returned.
If the transfer time out occurs error code 8001H is returned otherwise the
status is returned.
Prerequisites
The adapter must be configured by running setup.
Issue 2.4
15/07/99
Page 4
CALIBRE
Functional description
3.5.3.
The function waits for the bus to be free. Then sends the slave address with
the appropriate acknowledge.
The acknowledge is set ready for the data transfer after the address and
hence in read mode (odd address being sent) if only one byte is to be read
the setnack parameter must equal 1. If more than one byte is to be read or if
in write mode (even address being sent) then setnack must equal 0.
The function waits for the address to be sent. Should a time-out occur during
the sending of an address then an error code 8001H is returned, otherwise
the status is returned.
writebyte
Function specification
Int writebyte(int wrData)
Parameters are:
int wrData
This is the byte of data to be written.
Parameters returned
int ErrCode.
If the software fails to open a handle to the driver 0x9000 is returned.
If the transfer time out occurs error code 8004H is returned otherwise the
status is returned.
Prerequisites
Adapter must be configured using setup, start and write address sent by
sendaddress.
Functional description
The function writes the data to the adapter and then waits for it to be sent.
Should a time-out occur during the sending of the data then error code 8004H
is returned, otherwise the status is returned.
Writebyte is compatible with both master write and slave write modes.
3.5.4.
readbyte
Function specification
Int readbyte(int setnack)
Parameters are:
int setnack
This controls whether the adapter transmits an acknowledge down the I2C
bus on reception of a byte. The last byte received during a transfer must not
be acknowledged, in all other cases acknowledge must be enabled. If
setnack = 0 then acknowledge is enabled, if setnack = 1 then acknowledge is
disabled. Therefore, if the LAST BUT ONE byte is to be read, setnack should
be set to =1; in all other cases it is to be set = 0 (in the case of reading 1 byte
only, the acknowledge will have been disabled by sendaddress and so should
now be enabled again after reading the data, hence setnack = 0 for reading a
single byte of data).
The first read from the adapter following a write to it will result in the data that
was written being returned. This data MUST be read and discarded before
real data can be read, DO NOT count this extra read when considering
whether or not to acknowledge.
Parameters returned
int I2CData
If the software fails to open a handle to the driver 0x9000 is returned.
If a time-out occurs the ErrCode 8005H is returned, otherwise the data is
returned.
Prerequisites
Adapter must be configured using setup, start and read address sent by
sendaddress.
Issue 2.4
15/07/99
Page 5
CALIBRE
Functional description
3.5.5.
If setnack is 1 the function writes 40H to the control register to establish the
correct acknowledge procedure.
The data is read from the adapter.
Readbyte is compatible with both master read and slave read modes.
sendstop
Function specification
Int sendstop( )
Parameters are:
None.
Parameters returned
int ErrCode.
If the software fails to open a handle to the driver 0x9000 is returned.
If the transfer time out occurs error code 8002H is returned otherwise the
status is returned.
Prerequisites
Adapter must be configured using setup. Should normally only be used at the
end of a transmission. Correct acknowledge sequence must have been
applied if the transmission was a read.
Functional description
Instructs the adapter to send a stop code and wait for it to be sent.
Should a time-out occur during the sending of a stop then an error code
8002H is returned, otherwise the status is returned.
3.5.6.
restart
Function specification
Int restart(int slaveaddress, int setnack)
Parameters are:
int slaveaddress
The address to be accessed via the I2C, e.g. A1H.
int setnack
This controls whether the adapter transmits an acknowledge down the I2C
bus on reception of a byte. The last byte received during a transfer must not
be acknowledged, in all other cases acknowledge must be enabled. If
setnack = 0 then acknowledge is enabled, if setnack = 1 then acknowledge is
disabled. Therefore, if a read (odd numbered) address is being sent AND only
1 Byte is to be read, setnack should be set to = 1; in all other cases it must be
clear = 0.
Parameters returned
int ErrCode
If the software fails to open a handle to the driver 0x9000 is returned.
If the transfer time out occurs error code 8003H is returned otherwise the
status is returned.
Prerequisites
Adapter must be configured using setup. A start and slave address must
have previously been sent using sendaddress.
Usually a data pointer would already have been written using writebyte.
Functional description
Sends a start code and the slave address specified and presets the
acknowledge status depending on the value of setnack.
The acknowledge is set ready for the data transfer after the address and
hence in read mode (odd address being sent) if only one byte is to be read
the setnack parameter must equal 1. If more than one byte is to be read or if
in write mode (even address being sent) then setnack must equal 0.
The function waits for the address to be sent. Should a time-out occur during
the sending of an address then an error code 8003H is returned, otherwise
the status is returned.
Issue 2.4
15/07/99
Page 6
CALIBRE
3.5.7.
getstatus
Function specification: Int getstatus(void)
Parameters are:
None.
Parameters returned
int I2Cstatus
If the software fails to open a handle to the driver 0x9000 is returned
otherwise the current value of the bus status is returned.
Prerequisites
Adapter must be configured using setup.
Functional description
The function reads status word from the adapter and returns it.
3.5.8.
recover
Function specification
Int recover(void)
Parameters are:
None.
Parameters returned
int ErrCode.
If the software fails to open a handle to the driver 0x9000 is returned.
If the bus recovery failed error code 8006H is returned otherwise the status is
returned.
Prerequisites
Adapter must be configured using setup.
Functional description
This function issues two consecutive stop commands on the bus, with a delay
in between. It then clears the adapter registers and reads the status. This
should normally set the adapter into a known idle state when a bus error or
other problem has occurred.
If the status does not indicate bus free or the Bus Error bit is still set then
8006H is returned otherwise the status is returned.
3.5.9.
slavelastbyte
Function specification
void slavelastbyte( )
Parameters returned
If the software fails to open a handle to the driver 0x9000 is returned
otherwise the function returns 0.
Prerequisites
Adapter must be configured using setup. This function would normally only
be called following the end of a transmission in slave write mode - when the
adapter is being read as a slave, by another master, not when writing to a
slave using the adapter.
Functional description
This function is used when the adapter is a slave being read by a master
elsewhere on the bus - the adapter is in slave write mode. The function must
be called immediately after the master indicates the last byte has been read
(by not acknowledging that byte). This function is required to clear the I2C
data lines so that the master can send a stop signal.
Issue 2.4
15/07/99
Page 7
CALIBRE
THE MOST COMMONLY ASKED I2C QUESTIONS
4.1.
General Questions
Question
Answer
Will my adapter work in a Pentium PC?
Yes and there is no need to alter LK 4 from the position in which your adapter was
shipped.
Question
Answer
Will my adapter run I2C clock speeds greater than 90KHz?
At the moment your adapter is limited by the Bus Controller chip fitted, to a maximum
of 90KHz as a master and 100KHz as a slave.
Question
Answer
Will my adapter work under Windows NT4* or Windows 95*?
The adapter will work under both these systems without problems, but the software
supplied with the adapter is 16 bit only. Windows NT and Windows 95 DLLs are
available please contact our sales team for further information.
* All trade marks acknowledged
Question
Answer
I get corrupted transfers why is this?
The most likely reason for corrupted transfers is either incorrect bus termination or
excessive capacitance - see the manual for details.
Question
Answer
Do you have software to talk to my........?
Unfortunately there are too many I2C devices for us to be able to offer complete
solutions - although we can supply a windows based application called WINI2C which
is designed for those just starting I2C or wishing to perform simple I2C tasks, please
contact our sales team or look on our web site, www.calibreuk.com for further
information.
Question
I am trying to read from a device, the first time my software works fine but when
I try again I can't get anything what's wrong?
Please check that you are changing the value of Setnack in accordance with the
manual, it is likely that you have not made Setnack 1 for the last AND last but one
bytes being read.
Answer
4.2.
Question
Answer
4.3.
Question
DOS Software Questions
My I2C adapter locks up with a constant status - why?
If you are using either the 'C' or Basic library functions supplied with the adapter on a
fast PC it is possible that the PC is polling the status register too quickly, the simplest
way to prevent this is to add a small delay prior to reading the status in the getstatus
routine. Alternatively use the windows DLL supplied as these automatically allow for
speed of the PC at run-time.
WINDOWS 95 and NT Questions
Answer
My software cannot find the adapter. Your Windows software reports that it
cannot configure the adapter. Why is this?
Have you registered the device driver as detailed in the software manual? If so check
that the address links (see adapter manual for details) are correct for the location at
which you registered the driver.
Question
Answer
I think I have registered the driver how can I find out if I have?
You need to inspect the registry as follows
Windows 95 START - Run regedit
Issue 2.4
15/07/99
Page 8
CALIBRE
HKEY_LOCAL_MACHINE
|
|--SYSTEM
|
|--CurrentControlSet
|
|--Services
|
|--Class
|
|--WinRT
|
|--WinRTdev0
|
|--Parameters
|--Section0
|--Section1
Windows NT START - Run regedit
HKEY_LOCAL_MACHINE
|
|--SYSTEM
|
|--CurrentControlSet
|
|--Services
|
|--WinRT
|
|--WinRTdev0
|
|--Parameters
|--Section0
|--Section1
Question
Answer
I am using your Windows 95 / NT DLL and I am always getting a time out error
code. Why?
Check the Syntax of the setup function, this problem is most usually caused by
swapping the Status Wait and Sclk parameters.
The correct syntax is i2cstatus = setup (baseaddress, ownaddress, sclk, statuswait)
Question
Answer
I have read the manual and still cannot get the communications to run. What
do I do next?
Check that you have fully implemented the protocol between the adapter and the
other I2C devices see the device manufacturers data sheet for details.
Check that the software you have written is logically and syntactically correct - this is
probably the most common cause of software faults we have to deal with.
Send us the following details:1)The link settings of the adapter.
2)A sketch of the relevant I2C hardware including the location of bus termination.
3)The type and speed of processor within your PC and which operating system, you
are running.
4)Brief software listings, or which Calibre software you are running.
5)The serial number of your I2C adapter, or when you purchased it.
Issue 2.4
15/07/99
Page 9
CALIBRE
PLEASE EMAIL YOUR QUERY TO:
techsupport@calibreuk.com
OR FAX YOUR QUERY TO:
44-1274-730960
We will endeavour to help you.
Issue 2.4
15/07/99
Page 10
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising