Unit I2C
Return to Unit Reference
Description
Ultibo I2C interface unit
I2C (Inter-Integrated Circuit) is a serial bus for communication between peripheral components.
Originally invented by Phillips the I2C protocol is used by thousands of common chips that perform a wide range of tasks such as real time clocks, temperature and other sensors, small LCD displays and many more.
Each device is assigned a 7bit address which is used by the host (or master) to signal the device that a message written to the bus is intended for that device or that the host wants to read data from that device.
Speeds range from 10Kbps to 3.4Mbps although the typical speed is either 100Kbps or 400Kbps.
This unit implements the standardized interface for I2C devices and allows reading or writing to a specific address, setting a clock rate for the communication and determining device properties.
For the purpose of this interface a device is the I2C controller attached to the local system and may be either a master or a slave. Since the protocol does not include any form of enumeration or identification the interface does not attempt to represent the devices connected to the bus,any driver written to communicate with a connected I2C device should know (or allow configuration of) the address to read and write to and the specific message format required for that device. The Intel System Management Bus (SMBus) is a variation of the I2C bus and in certain cases the two are compatible with each other.
Constants
I2C_*
I2C_NAME_PREFIX = 'I2C';
|
Name prefix for I2C Devices |
I2C_TYPE_*
I2C_TYPE_NONE = 0;
|
I2C_STATE_*
I2C_STATE_DISABLED = 0;
|
|
I2C_STATE_ENABLED = 1;
|
I2C_FLAG_*
I2C_FLAG_NONE = $00000000;
|
|
I2C_FLAG_SLAVE = $00000001;
|
Device is a slave not a master |
I2C_FLAG_10BIT = $00000002;
|
Device supports 10bit addressing |
I2C_FLAG_16BIT = $00000004;
|
Device supports 16bit addressing |
I2C_LOG_*
I2C_LOG_LEVEL_DEBUG = LOG_LEVEL_DEBUG;
|
I2C debugging messages |
I2C_LOG_LEVEL_INFO = LOG_LEVEL_INFO;
|
I2C informational messages, such as a device being attached or detached |
I2C_LOG_LEVEL_ERROR = LOG_LEVEL_ERROR;
|
I2C error messages |
I2C_LOG_LEVEL_NONE = LOG_LEVEL_NONE;
|
No I2C messages |
Type definitions
I2C properties
PI2CProperties = ^TI2CProperties;
TI2CProperties = record
Flags:LongWord;
|
Device flags (eg I2C_FLAG_SLAVE) |
MaxSize:LongWord;
|
Maximum supported data transfer size |
MinClock:LongWord;
|
Minimum supported clock rate |
MaxClock:LongWord;
|
Maximum supported clock rate |
ClockRate:LongWord;
|
Current clock rate |
SlaveAddress:Word;
|
Current slave address |
I2C enumeration callback
TI2CEnumerate = function(I2C:PI2CDevice; Data:Pointer):LongWord;
|
I2C notification callback
TI2CNotification = function(Device:PDevice; Data:Pointer; Notification:LongWord):LongWord;
|
I2C device start
TI2CDeviceStart = function(I2C:PI2CDevice;Rate:LongWord):LongWord;
|
I2C device stop
TI2CDeviceStop = function(I2C:PI2CDevice):LongWord;
|
I2C device read
TI2CDeviceRead = function(I2C:PI2CDevice; Address:Word; Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;
|
I2C device write
TI2CDeviceWrite = function(I2C:PI2CDevice; Address:Word; Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;
|
I2C device write read
TI2CDeviceWriteRead = function(I2C:PI2CDevice; Address:Word; Initial:Pointer; Len:LongWord; Data:Pointer; Size:LongWord; var Count:LongWord):LongWord;
|
I2C device write write
TI2CDeviceWriteWrite = function(I2C:PI2CDevice; Address:Word; Initial:Pointer; Len:LongWord; Data:Pointer; Size:LongWord; var Count:LongWord):LongWord;
|
I2C device get rate
TI2CDeviceGetRate = function(I2C:PI2CDevice):LongWord;
|
I2C device set rate
TI2CDeviceSetRate = function(I2C:PI2CDevice; Rate:LongWord):LongWord;
|
I2C device get address
TI2CDeviceGetAddress = function(I2C:PI2CDevice):Word;
|
I2C device set address
TI2CDeviceSetAddress = function(I2C:PI2CDevice; Address:Word):LongWord;
|
I2C device get properties
TI2CDeviceGetProperties = function(I2C:PI2CDevice; Properties:PI2CProperties):LongWord;
|
I2C device
PI2CDevice = ^TI2CDevice;
TI2CDevice = record
Device Properties | |
Device:TDevice;
|
The Device entry for this I2C |
I2C Properties | |
I2CId:LongWord;
|
Unique Id of this I2C in the I2C table |
I2CState:LongWord;
|
I2C state (eg I2C_STATE_ENABLED) |
DeviceStart:TI2CDeviceStart;
|
A Device specific DeviceStart method implementing the standard I2C device interface (Mandatory) |
DeviceStop:TI2CDeviceStop;
|
A Device specific DeviceStop method implementing the standard I2C device interface (Mandatory) |
DeviceRead:TI2CDeviceRead;
|
A Device specific DeviceRead method implementing the standard I2C device interface (Mandatory) |
DeviceWrite:TI2CDeviceWrite;
|
A Device specific DeviceWrite method implementing the standard I2C device interface (Mandatory) |
DeviceWriteRead:TI2CDeviceWriteRead;
|
A Device specific DeviceWriteRead method implementing the standard I2C device interface (Or nil if the default method is suitable) |
DeviceWriteWrite:TI2CDeviceWriteWrite;
|
A Device specific DeviceWriteWrite method implementing the standard I2C device interface (Or nil if the default method is suitable) |
DeviceGetRate:TI2CDeviceGetRate;
|
A Device specific DeviceGetRate method implementing the standard I2C device interface (Or nil if the default method is suitable) |
DeviceSetRate:TI2CDeviceSetRate;
|
A Device specific DeviceSetRate method implementing the standard I2C device interface (Or nil if the default method is suitable) |
DeviceGetAddress:TI2CDeviceGetAddress;
|
A Device specific DeviceGetAddress method implementing the standard I2C device interface (Or nil if the default method is suitable) |
DeviceSetAddress:TI2CDeviceSetAddress;
|
A Device specific DeviceSetAddress method implementing the standard I2C device interface (Or nil if the default method is suitable) |
DeviceProperties:TI2CDeviceProperties;
|
A Device specific DeviceProperties method implementing the standard I2C device interface (Or nil if the default method is suitable) |
Statistics Properties | |
ReadCount:LongWord;
|
|
WriteCount:LongWord;
|
|
ReadErrors:LongWord;
|
|
WriteErrors:LongWord;
|
|
Driver Properties | |
Lock:TMutexHandle;
|
Device lock |
Wait:TSemaphoreHandle;
|
Read/Write wait event |
ClockRate:LongWord;
|
Clock rate (Hz) |
SlaveAddress:Word;
|
Slave address |
Properties:TI2CProperties;
|
Device properties |
Internal Properties | |
Prev:PI2CDevice;
|
Previous entry in I2C table |
Next:PI2CDevice;
|
Next entry in I2C table |
Public variables
I2C logging
I2C_DEFAULT_LOG_LEVEL:LongWord = I2C_LOG_LEVEL_DEBUG;
|
Minimum level for I2C messages. Only messages with level greater than or equal to this will be printed. |
I2C_LOG_ENABLED:Boolean;
|
Function declarations
Initialization functions
procedure I2CInit;
Note | Called only during system startup |
---|
I2C functions
function I2CDeviceStart(I2C:PI2CDevice; Rate:LongWord):LongWord;
I2C | The I2C device to start |
---|---|
Rate | The clock rate to set for the device (0 to use the default rate |
Return | ERROR_SUCCESS if completed or another error code on failure |
function I2CDeviceStop(I2C:PI2CDevice):LongWord;
I2C | The I2C device to stop |
---|---|
Return | ERROR_SUCCESS if completed or another error code on failure |
function I2CDeviceRead(I2C:PI2CDevice; Address:Word; Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;
I2C | The I2C device to read from |
---|---|
Address | The slave address to read from (I2C_ADDRESS_INVALID to use the current address) |
Buffer | Pointer to a buffer to receive the data |
Size | The size of the buffer |
Count | The number of bytes read on return |
Return | ERROR_SUCCESS if completed or another error code on failure |
function I2CDeviceWrite(I2C:PI2CDevice; Address:Word; Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;
I2C | The I2C device to write to |
---|---|
Address | The slave address to write to (I2C_ADDRESS_INVALID to use the current address) |
Buffer | Pointer to a buffer of data to transmit |
Size | The size of the buffer |
Count | The number of bytes written on return |
Return | ERROR_SUCCESS if completed or another error code on failure |
function I2CDeviceWriteRead(I2C:PI2CDevice; Address:Word; Initial:Pointer; Len:LongWord; Data:Pointer; Size:LongWord; var Count:LongWord):LongWord;
I2C | The I2C device to write to and read from |
---|---|
Address | The slave address to write to (I2C_ADDRESS_INVALID to use the current address) |
Initial | Pointer to the initial buffer to transmit |
Len | The size of the initial buffer |
Data | Pointer to a buffer to receive the data |
Size | The size of the data buffer |
Count | The number of bytes read on return |
Return | ERROR_SUCCESS if completed or another error code on failure |
function I2CDeviceWriteWrite(I2C:PI2CDevice; Address:Word; Initial:Pointer; Len:LongWord; Data:Pointer; Size:LongWord; var Count:LongWord):LongWord;
I2C | The I2C device to write to |
---|---|
Address | The slave address to write to (I2C_ADDRESS_INVALID to use the current address) |
Initial | Pointer to the initial buffer to transmit |
Len | The size of the initial buffer |
Data | Pointer to a buffer of data to transmit |
Size | The size of the data buffer |
Count | The number of bytes of data written on return |
Return | ERROR_SUCCESS if completed or another error code on failure |
function I2CDeviceGetRate(I2C:PI2CDevice):LongWord;
I2C | The I2C device to get the clock rate from |
---|---|
Return | The clock rate in Hz or 0 on failure |
function I2CDeviceSetRate(I2C:PI2CDevice; Rate:LongWord):LongWord;
I2C | The I2C device to set the clock rate for |
---|---|
Rate | The clock rate to set in Hz |
Return | ERROR_SUCCESS if completed or another error code on failure |
function I2CDeviceGetAddress(I2C:PI2CDevice):Word;
I2C | The I2C device to get the slave address from |
---|---|
Return | The slave address or I2C_ADDRESS_INVALID on failure |
function I2CDeviceSetAddress(I2C:PI2CDevice; Address:Word):LongWord;
I2C | The I2C device to set the slave address for |
---|---|
Address | The slave address to set |
Return | ERROR_SUCCESS if completed or another error code on failure |
function I2CDeviceProperties(I2C:PI2CDevice; Properties:PI2CProperties):LongWord; inline;
I2C | The I2C device to get properties from |
---|---|
Properties | Pointer to a TI2CProperties structure to fill in |
Return | ERROR_SUCCESS if completed or another error code on failure |
Note | Replaced by I2CDeviceGetProperties for consistency |
function I2CDeviceGetProperties(I2C:PI2CDevice; Properties:PI2CProperties):LongWord;
I2C | The I2C device to get properties from |
---|---|
Properties | Pointer to a TI2CProperties structure to fill in |
Return | ERROR_SUCCESS if completed or another error code on failure |
function I2CDeviceCreate:PI2CDevice;
Return | Pointer to new I2C entry or nil if I2C could not be created |
---|
function I2CDeviceCreateEx(Size:LongWord):PI2CDevice;
Size | Size in bytes to allocate for new I2C (Including the I2C entry) |
---|---|
Return | Pointer to new I2C entry or nil if I2C could not be created |
function I2CDeviceDestroy(I2C:PI2CDevice):LongWord;
Note | None documented |
---|
function I2CDeviceRegister(I2C:PI2CDevice):LongWord;
Note | None documented |
---|
function I2CDeviceDeregister(I2C:PI2CDevice):LongWord;
Note | None documented |
---|
function I2CDeviceFind(I2CId:LongWord):PI2CDevice;
Note | None documented |
---|
function I2CDeviceFindByName(const Name:String):PI2CDevice; inline;
Note | None documented |
---|
function I2CDeviceFindByDescription(const Description:String):PI2CDevice; inline;
Note | None documented |
---|
function I2CDeviceEnumerate(Callback:TI2CEnumerate; Data:Pointer):LongWord;
Note | None documented |
---|
function I2CDeviceNotification(I2C:PI2CDevice; Callback:TI2CNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;
Note | None documented |
---|
RTL I2C functions
function SysI2CAvailable:Boolean;
Note | None documented |
---|
function SysI2CStart(Rate:LongWord):LongWord;
Rate | The clock rate to set for the device (0 to use the default rate) |
---|---|
Return | ERROR_SUCCESS if completed or another error code on failure |
function SysI2CStop:LongWord;
Return | ERROR_SUCCESS if completed or another error code on failure |
---|
function SysI2CRead(Address:Word; Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;
Address | The slave address to read from (I2C_ADDRESS_INVALID to use the current address) |
---|---|
Buffer | Pointer to a buffer to receive the data |
Size | The size of the buffer |
Count | The number of bytes read on return |
Return | ERROR_SUCCESS if completed or another error code on failure |
function SysI2CWrite(Address:Word; Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;
Address | The slave address to write to (I2C_ADDRESS_INVALID to use the current address) |
---|---|
Buffer | Pointer to a buffer of data to transmit |
Size | The size of the buffer |
Count | The number of bytes written on return |
Return | ERROR_SUCCESS if completed or another error code on failure |
function SysI2CWriteRead(Address:Word; Initial:Pointer; Len:LongWord; Data:Pointer; Size:LongWord; var Count:LongWord):LongWord;
Address | The slave address to write to (I2C_ADDRESS_INVALID to use the current address) |
---|---|
Initial | Pointer to the initial buffer to transmit |
Len | The size of the initial buffer |
Data | Pointer to a buffer to receive the data |
Size | The size of the data buffer |
Count | The number of bytes read on return |
Return | ERROR_SUCCESS if completed or another error code on failure |
function SysI2CWriteWrite(Address:Word; Initial:Pointer; Len:LongWord; Data:Pointer; Size:LongWord; var Count:LongWord):LongWord;
Address | The slave address to write to (I2C_ADDRESS_INVALID to use the current address) |
---|---|
Initial | Pointer to the initial buffer to transmit |
Len | The size of the initial buffer |
Data | Pointer to a buffer of data to transmit |
Size | The size of the data buffer |
Count | The number of bytes of data written on return |
Return | ERROR_SUCCESS if completed or another error code on failure |
function SysI2CGetRate:LongWord;
Return | The clock rate in Hz or 0 on failure |
---|
function SysI2CSetRate(Rate:LongWord):LongWord;
Rate | The clock rate to set in Hz |
---|---|
Return | ERROR_SUCCESS if completed or another error code on failure |
function SysI2CGetAddress:Word;
Return | The slave address or I2C_ADDRESS_INVALID on failure |
---|
function SysI2CSetAddress(Address:Word):LongWord;
Address | The slave address to set |
---|---|
Return | ERROR_SUCCESS if completed or another error code on failure |
I2C helper functions
function I2CGetCount:LongWord; inline;
Note | None documented |
---|
function I2CDeviceGetDefault:PI2CDevice; inline;
Note | None documented |
---|
function I2CDeviceSetDefault(I2C:PI2CDevice):LongWord;
Note | None documented |
---|
function I2CDeviceCheck(I2C:PI2CDevice):PI2CDevice;
Note | None documented |
---|
procedure I2CLog(Level:LongWord; I2C:PI2CDevice; const AText:String);
Note | None documented |
---|
procedure I2CLogInfo(I2C:PI2CDevice; const AText:String); inline;
Note | None documented |
---|
procedure I2CLogError(I2C:PI2CDevice; const AText:String); inline;
Note | None documented |
---|
procedure I2CLogDebug(I2C:PI2CDevice; const AText:String); inline;
Note | None documented |
---|
Return to Unit Reference