:Revision=3
:html
<<
128.119
I2C-Object|I2C
$NoSort
--
The IP-Object <!RW>I2C ensures access to an IC-interface
(Inter-IC-Connection).

The access is possible over an IC-interface which must be defined and addressed by its name.
>>

<<
128.119.1
Functions of the I2C-Object|Functions
--
>>
<<
128.119.1.1
I2C.Execute|Execute
--
<!DEF>
function <!TW>I2C.Execute (sName, sCommand : string) : string;
<!TXT>
Executes the commands coded in the <!PW>sCommand string on the IC interface <!PW>sName.

 <!PW>sCommand is processed from left to right. It may be composed of the following characters (both upper- and lower case can be used):

<!STBL>
<!+>Character<!+>Action<!>
<!c>S<!>generates a start condition<!>
<!c>P<!>generates a stop condition<!>
<!c>00..FF<!>send byte <!>
<!c>K<!>read Ack on the last finished byte<!>
<!c>Q<!>read byte with Ack<!>
<!c>R<!>read byte without Ack<!>
<!c>L<!>sets SDA on high<!>
<!c>M<!>sets SDA on low<!>
<!c>N<!>returns the status of SDA<!>
<!c>G<!>sets SCL on high<!>
<!c>H<!>sets SCL on low<!>
<tr><td colspan=2>all other characters are ignored<!>
<!ETBL>

The values read as reaction to K,N,Q and R are sent back as result string - Bit values as '-' or '+', bytes in hex format ('00'..'FF').

Example:

In the command:
<!CODE>
sData:=I2C.Execute ('I2C_MCD', 'SA000SA1QQQQQQQRP');
<!TXT>
the command has the following effects:
<!CODE>
S  - generate start condition
A0 - send byte A0 (addressing mode of the IC-component - write access)
00 - send byte 00 (second part of the address)
S  - generate start condition
A1 - send byte A1 (addressing mode of the IC-component - read access)
Q  - read byte with Ack (7 times in total)
R  - read byte without Ack - signals the end of the reading
P  - generate stop condition
<!TXT>
Thus the execute function reads in 8 bytes from the IC component.
>>
<<
128.119.1.2
I2C.Read|Read
--
<!DEF>
function <!TW>I2C.Read (sName : string [; rAck : real]) : real;
<!TXT>
Reads in a byte from the IC Bus. Before that, one of the components must be addressed and brougt in read mode with a command on the bus. If  <!PW>rAck is not specified or is <!RW>true, then the read byte is confirmed with an acknowledge. If <!PW>rAck is <!RW>false, a negative acknowledge is sent back.
>>
<<
128.119.1.3
I2C.Ack|Ack
--
<!DEF>
function <!TW>I2C.Ack (sName : string) : real;
<!TXT>
Returns the value of the Ack-Flags which was last read in, i.e. the response to the last output byte.
>>
<<
128.119.2
Procedures of the I2C-Object|Procedures
--
>>
<<
128.119.2.1
I2C.Start|Start
--
<!DEF>
procedure <!TW>I2C.Start (sName : string);
<!TXT>
Generates a start condition on the IC Bus <!PW>sName.
>>
<<
128.119.2.2
I2C.Stop|Stop
--
<!DEF>
procedure <!TW>I2C.Stop (sName : string);
<!TXT>
Generates a stop condition on the IC Bus <!PW>sName.
>>
<<
128.119.2.7
I2C.Set|Set
--
<!DEF>
procedure <!TW>I2C.Set  (sName : string; rLine : real; <!RW>High|<!RW>Low);
<!TXT>
Sets the selected line <!PW>rLine (1=SDA, 2=SCL) on the IC Bus <!PW>sName to the specified level.

Special statuses, which are not according to the normal IC protocol, can be generated with this command.

For normal communication this command is not necessary.
>>
<<
128.119.2.10
I2C.Send|Send
--
<!DEF>
procedure <!TW>I2C.Send (sName : string; vData : vector);
<!TXT>
Sends the bytes in the vector <!PW>vData to the IC Bus <!PW>sName.
>>
<<
128.119.2.11
I2C.Reset|Reset
--
<!DEF>
procedure <!TW>I2C.Reset;
<!TXT>
Executes a complete reset of the IC bus, whereas all settings will be set to the configuration settings.
>>
<<
128.119.4
I2C Bus Definition|Definition
--
IC Buses are defined in a separate file <!CW>(%SYS%\I2CBusses.Dat). If this file does not exist, then a default bus is defined internally via the ME3000 card.

Each (not empty) row of the file defines an I2C Bus. The number of defined buses is not limited.

Comments can be inserted with // or { and they always end at the end of the line.

The lines have the following format:
<!CODE>
<b><!SW>BusName <!SW>BusType (<!SW>BusData) <!SW>Info</b>
<!TXT>
The individual elements are separated by blanks or tabulators, but they must necessarily be in one line.

 <!SW>BusName is the name used in the interpreter in order to address the bus. This name must be unique and should comply with the rules for the IP-identifiers. Both upper- and lower case is allowed.

 <!SW>BusType determines the type of the bus (its hardware). It must be one of the IC  bus types defined in the program. See below.

 <!SW>BusData determines the hardware that is going to be used and other options. It depends on the bus type which inputs are valid in the bus data. If no data is required, then an empty bracket () must be specified.

 <!SW>Info is an optional description of the bus. It is not used by the program.
>>
<<
128.119.4.1
BusType I2CviaME3000|I2CviaME3000
--
The <!SW>I2CviaME3000 bus type creates an IC bus via the digital IO lines of the ME3000 card.
2 output-lines are used for SCL and SDA-out and one input-line for SDA-in. SDA-out and SDA-in must be connected over an external circuit.

Possible items in data:
<!STBL>
<!+>Item<!+>Allowed<!+>Default<!+>Meaning<!>
<!c>SDAIn<!>A0..A15<!>A13<!>Line used to read back SDA<!>
<!c>SDAOut<!>B0..B15<!>B13<!>Line used to transmit SDA<!>
<!c>SCLOut<!>B0..B15<!>B14<!>Line used to transmit SCL<!>
<!ETBL>

The values set as default are MCD-Bus lines which are double used for IC-purposes.

This IC-Bus controls the internal IC-Function. Therefore, for the external use in the test device an IC-Bus should be defined with different lines.

Reasonable ranges for
<ul indent=13>
<li>SDAIn : A0..A11</li>
<li>SDAout : B0..B7</li>
<li>SCLOut : B0..B7</li>
</ul>

Example of a bus-desinition:
<!CODE>
//-------------------------------------------------------------------
// BusName   Type          Data                          Info
//-------------------------------------------------------------------
I2C_ME       I2CviaME3000 (SDAIn=A7;SDAOut=B7;SCLOut=B6)
<!TXT>
>>
<<
128.119.4.2
BusType I2CviaRS232|I2CviaRS232
--
The bus type <!SW>I2CviaRS232 creates an IC Bus over the handshake lines of the RS232-interface.

The following pin-assignment is used:

<!STBL>
<!+>RS232-Pin<!+>IC Function<!>
<!c>RTS<!>SDA-out<!>
<!c>CTS<!>SDA-in<!>
<!c>DTR<!>SCL-out<!>
<!ETBL>
<!REM>
It is not possible to change the assignement.
<!TXT>

Possible items in BusData:
<!STBL>
<!+>Name<!+>Allowed<!+>Default<!+>Meaning<!>
<!c>Port<!>1, 2, 3...<!>-<!>Number of the Com-Port.<br><b>Must be specified, no default value!</b><!>
<!c>Invert<!>false, true<!>true<!>To be set to true, if the lines are inverted externally by a Max232 or something else <!>
<!ETBL>

The port can still be used for communication; the IC-Bus only influences the handshake signals.

It is mot mandatory to define the port must as one of the serial ports, but it can be defined so. It is also irrelevant, whether the Port has been already opened by the RS232-Object or not.

In any case the Execute command is preferred for this port type out of performance reasons (allocation and return of the port) to a command orientated programming; therefore:
<!CODE>
vData:=[];
I2C.Start ('I2CCom');
I2C.Send  ('I2CCom', [$A0, $00]);
I2C.Start ('I2CCom');
I2C.Send ('I2CCom', [$A1]);
for i:=1 to 8 do begin
  vData:=vData+I2CBus.Read ('I2CCom', i<8);
end;
I2C.Stop ('I2CCom');
<!TXT>
better:
<!CODE>
vData:=HexToBVect(I2CBus.Execute ('I2C', 'SA000SA1QQQQQQQRP'));
<!TXT>

For best performance a 'normal' RS232 Port should be defined and opened on this COM-Port, since the IC Routines use in this case the handle of the RS232 port and must not request a separate handle from Windows for every access.

Example of a bus definition:
<!CODE>
//-------------------------------------------------------------------
// BusName   Type         Data                  Info
//-------------------------------------------------------------------
I2C_Adapter  I2CviaRS232 (Port=1; Invert=true)  IC over RS232 Port 1
<!TXT>
>>

<<
128.119.4.3
Bustypes, using a SerIO Module|I2C via SerIO
--
Module, that are accessed via the RS232 interface and the SerIO Bus, e.g.:
<ul indent=13>
<li>MechIO moduls</li>
<li>AdapterCPU modules</li>
<li>IMeasX4 modules, etc.</li>
</UL>
implement a IC interface too.

For a successful access, the following systems have to be activated and running:
<ul indent=13>
<li>the RS232 interfaces globally</li>
<li>the RS232 interface used for the SerIO bus of the module</li>
<li>the class of the module globally</li>
<li>the module used as gateway</li>
</ul>
 <i>in other words: the gateway modul must be ready to work.</i>

Since the SerIO modules have only limited gateway capabilities regarding the IC bus, some low level access is not possible resp. results in invalid data.

Supported features:
<ul indent=13>
<li><!RW>I2C.Start </li>
<li><!RW>I2C.Send</li>
<li><!RW>I2C.Stop </li>
</ul>

Partial supported features:
<ul indent=13>
<li><!RW>I2CRead - will send always a NoAck!</li>
</ul>

Unsupported features:
<ul indent=13>
<li><!RW>I2C.Ack</li>
<li><!RW>I2C.Set</li>
</ul>

Special case: <!RW>I2C.Execute 
<!STBL>
<!+>Character<!+>Function<!+>supported by the modules?<!>
<!>S, P   <!>start-/stop condition<!>supported<!>
<!>00 .. FF <!>send byte<!>supported<!>
<!>K      <!>read Ack<!>not supported, returns '?'<!>
<!>Q, R   <!>read byte with(out) Ack<!>supported, but will generate always a NoAck for the last byte (even for Q)<!>
<!>G, H   <!>set SCL to high/low<!>not supported<!>
<!>L, M   <!>set SDA to high/low<!>not supported<!>
<!>N      <!>return state of SDA<!>not supported, returns '?'<!>
<!ETBL>
>>

<<
128.119.4.3.1
BusType I2CviaMechIO|I2CviaMechIO
--
The I2CviaMechIO bus type uses a mechanic module as gateway for the IC Bus.

 <a href="128.119.4.3">Important information about using a SerIO module as IC gateway</a>

Possible items in BusData:
<!STBL>
<!+>Name<!+>Allowed<!+>Default<!+>Meaning</b><!>
<!c>Module<!>1, 2, 3...<!>-<!>Number of the MechIO-Module.<br><b>Must be specified, no default value!</b><!>
<!ETBL>

Example of a bus definition:
<!CODE>
//-------------------------------------------------------------------
// BusName   Type         Data                  Info
//-------------------------------------------------------------------
I2C_MechIO  I2CviaMechIO (Modul=1)              IC over mechanic module 1
<!TXT>
>>
<<
128.119.4.3.2
BusTyp I2CViaAdapCpu|I2CViaAdapCpu
--
The I2CViaAdapCpu bus type uses an adapter-CPU module as gateway for the IC Bus.

 <a href="128.119.4.3">Important information about using a SerIO module as IC gateway</a>

Possible items in BusData:
<!STBL>
<!+>Name<!+>Allowed<!+>Default<!+>Meaning</b><!>
<!c>Module<!>1, 2, 3...<!>-<!>Number of the AdapterCPU-Module.<br><b>Must be specified, no default value!</b><!>
<!ETBL>

Example of a bus definition:
<!CODE>
//-------------------------------------------------------------------
// BusName   Type           Data                Info
//-------------------------------------------------------------------
I2C_AdapCPU  I2CviaAdapCPU (Modul=1)            IC over adapter CPU Module 1
<!TXT>
>>
<<
128.119.4.3.3
BusTyp I2CViaIMeasX4|I2CViaIMeasX4
--
The I2CViaIMeasX4 bus type uses a 4-channel current measurement module (IMeasX4) as gateway for the IC Bus.

 <a href="128.119.4.3">Important information about using a SerIO module as IC gateway</a>

Possible items in BusData:
<!STBL>
<!+>Name<!+>Allowed<!+>Default<!+>Meaning</b><!>
<!c>Module<!>1, 2, 3...<!>-<!>Number of the IMEASx4-Module.<br><b>Must be specified, no default value!</b><!>
<!ETBL>

Example of a bus definition:
<!CODE>
//-------------------------------------------------------------------
// BusName   Type            Data                Info
//-------------------------------------------------------------------
I2C_IMeasX4  I2CviaIMeasX4  (Modul=1)            IC over the 4-channel current measurement module 1
<!TXT>
>>
<<
128.119.4.3.4
BusTyp I2CviaRCMEas|I2CviaRCMEas
--
The <!SW>I2CviaRCMEas bus type uses a RC-Measureing module as gateway for the IC bus.

 <a href="128.119.4.3">Important information about using a SerIO module as IC gateway</a>

Possible items in BusData:
<!STBL>
<!+>Name<!+>Allowed<!+>Default<!+>Meaning</b><!>
<!c>Modul<!>1, 2, 3 ...<!>-<!>Number of the RCMEas-Module in the basic setup (not its address or the number of the COM port).<br><b>Must be given, no default!</b><!>
<!ETBL>

Example of a bus definition:
<!CODE>
//-------------------------------------------------------------------
// BusName   Type            Data                Info
//-------------------------------------------------------------------
I2C_RcMeasIO  I2CviaRCMEas (Modul=1)            IC over RC MEas Modul 1
<!TXT>
>>

<<
128.119.4.3.5
BusType I2CviaVideoAnalyzer|I2CviaVideoAnalyzer
--
The I2CviaVideoAnalyzer bus type uses a Video-Analyzer module as gateway for the IC Bus.

 <a href="128.119.4.3">Important information about using a SerIO module as IC gateway</a>

Possible items in BusData:
<!STBL>
<!+>Name<!+>Allowed<!+>Default<!+>Meaning</b><!>
<!c>Module<!>1, 2, 3...<!>-<!>Number of the Video-Analyzer module.<br><b>Must be specified, no default value!</b><!>
<!ETBL>

Example of a bus definition:
<!CODE>
//-----------------------------------------------------------------------------
// BusName        Type                Data      Info
//-----------------------------------------------------------------------------
I2C_VideoAnalyzer I2CviaVideoAnalyzer (Modul=1) IC over VideoAnalyzer module 1
<!TXT>
>>

<<
128.119.4.3.6
BusType I2CviaSerIOUnkown|I2CviaSerIOUnknown
--
The I2CviaSerIOUnknown bus type uses a MCD module as gateway for the IC Bus.

 <a href="128.119.4.3">Important information about using a SerIO module as IC gateway</a>

Possible items in BusData:
<!STBL>
<!+>Name<!+>Allowed<!+>Default<!+>Meaning</b><!>
<!c>Module<!>1, 2, 3...<!>-<!>Number of the SerIOUnknown-Module.<br><b>Must be specified, no default value!</b><!>
<!ETBL>

Example of a bus definition:
<!CODE>
//--------------------------------------------------------------------------
// BusName       Type               Data      Info
//--------------------------------------------------------------------------
I2C_SerIOUnknown I2CviaSerIOUnknown (Modul=1) IC over SerIOUnknown module 1
<!TXT>
>>
