i2c

Create I2C object

expand all in page

Description

I2C, or Inter-Integrated Circuit, is a chip-to-chip protocol supporting two-wire communication. An i2c object represents a connection between MATLAB® and an I2C adapter board. Supported adapters are the Total Phase Aardvark I2C/SPI Host Adapter and the National Instruments® USB-845x adapter board. The adapter has one or more sensor chips connected to it. MATLAB sends commands to the adapter board, which is the I2C controller device, in order to communicate with the chip, which is the I2C peripheral device. The i2c object in MATLAB always has the role of I2C controller and cannot be used in the peripheral role. Use fread and fwrite on the i2c object to communicate with the chip.

Creation

Syntax

i2cobj = i2c(vendor,boardIndex,remoteAddress)

Description

example

i2cobj = i2c(vendor,boardIndex,remoteAddress) creates an i2c object associated with vendor, boardIndex, and remoteAddress.

  • vendor must be either 'Aardvark', for use with the Total Phase Aardvark adapter, or 'NI845x', for use with the NI USB-845x adapter board. This input sets the Vendor property.

  • boardIndex specifies the board index of the adapter board and is 0 if you have only one adapter plugged into your computer. This input sets the BoardIndex property.

  • remoteAddress specifies the hex number address of the I2C peripheral device with which to communicate and is found in documentation or data sheet of the chip. This input sets the RemoteAddress property.

You can communicate with multiple I2C peripheral devices on the same adapter using a single i2c object. To communicate with a different I2C peripheral device, first create the object and use fopen to open a connection to the adapter. Then, change the RemoteAddress property to the address of the appropriate peripheral device. You can now use fwrite and fread to communicate with the specified peripheral device. For an example of this workflow, see Communicate with Multiple Peripheral Devices from NI USB-845x Adapter.

Properties

expand all

Board index of the adapter board, specified as an integer. If you have only one adapter plugged into your computer, the board index number is 0. If you have multiple adapters plugged in, each board is assigned a different board index number. Determine the board index using instrhwinfo('i2c','Aardvark') or instrhwinfo('i2c','NI845x'). This property can be set only at object creation.

Example: i2cobj = i2c('Aardvark',1,'50h') connects to the Aardvark adapter with an index value of 1.

Data Types: double | int8 | int16 | int32 | uint8 | uint16 | uint32

This property is read-only.

Unique identifier of the I2C controller communication device, specified as a character vector.

Example: i2cobj.BoardSerial returns the unique identifier of the Total Phase Aardvark adapter or NI USB-845x adapter.

Data Types: char

Bit rate of the adapter hardware, specified as a positive integer in kHz. Use a bit rate that is supported by the adapter and chips. The default is 100 kHz for both the Aardvark and USB-845x adapters.

Example: i2cobj.BitRate = 50 sets the bit rate to 50 kHz.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

I2C peripheral device address, specified as a number between 0 and 127 (inclusive), hex number, character vector, or string scalar. To identify the address of the chip, consult its documentation or data sheet. You can also find the address by scanning for instruments in the Test & Measurement Tool. In the tool, right-click the I2C node and select Scan for I2C adaptors. Any chips found by the scan is listed in the hardware tree. The listing includes the remote address of the chip.

You must specify this property during object creation and you can change it after object creation by using dot notation. Specify the peripheral address as a hexadecimal value in one of the following ways.

  • Append h to the end of the hex number as a character vector or string scalar.

  • Use the prefix 0x at the beginning of the hex number.

  • Use hex2dec with the hex number as the input argument.

To communicate with multiple I2C peripheral devices from one i2c object, set RemoteAddress to the appropriate peripheral device address. For an example of this workflow, see Communicate with Multiple Peripheral Devices from NI USB-845x Adapter.

Note

When reading this property using dot notation, it is returned as a numeric scalar representing the hex number. To convert back to the hex number, use dec2hex. For example, dec2hex(i2cObj.RemoteAddress) returns the I2C peripheral address as a hex number for the i2c object i2cObj.

Example: i2cobj = i2c('Aardvark',0,'50h') and i2cobj.RemoteAddress = '50h' specify an address of 50 hex.

Example: i2cobj = i2c('Aardvark',0,0x50) and i2cobj.RemoteAddress = 0x50 specify an address of 50 hex.

Example: i2cobj = i2c('Aardvark',0,hex2dec('50')) and i2cobj.RemoteAddress = hex2dec('50') specify an address of 50 hex.

Data Types: double | int8 | int16 | int32 | uint8 | uint16 | uint32 | char | string

I2C adapter vendor, specified as 'Aardvark' or 'NI845x'. The vendor is 'Aardvark' if you are using the Total Phase Aardvark adapter and 'NI845x' if you are using the NI USB-845x adapter. This property can be set only at object creation.

Example: i2cobj = i2c('Aardvark',0,'50h') connects to a Total Phase Aardvark adapter.

Example: i2cobj = i2c('NI845x',0,'50h') connects to a NI USB-845x adapter.

Data Types: char | string

Power to Aardvark adapter, specified as 'none' or 'both'. You can set this property for Aardvark adapters only. The value 'both' means power to both lines, if supported. The value 'none' means power to no lines.

Note

If Target Power is off in the Total Phase Control Center Serial Software, you might receive an error when you try to connect to the Aardvark adapter using fopen. To manually set the option, open the software and select the Target Power check box.

Example: i2cobj.TargetPower = 'both' provides power to both lines on the Aardvark adapter.

Data Types: char | string

Enabled pullup resistors, specified as 'both' or 'none'. The value 'both' enables 2k pullup resistors to protect hardware in the I2C device, if supported.

Devices differ in their use of pullups. The Aardvark and NI USB-8452 adapters have internal pullup resistors to tie both bus lines to VDD, and can be set programmatically. The NI USB-8451 adapter does not have this type of internal pullup resistor and, therefore, requires external pullups. Consult your device documentation to ensure that you are using the correct pullups.

Example: i2cobj.PullupResistors = 'none' disables pullup resistors.

Data Types: char | string

Object Functions

fopenConnect interface object to instrument
freadRead binary data from instrument
fwriteWrite binary data to instrument
fcloseDisconnect interface object from instrument
recordRecord data and event information to file

Examples

collapse all

Communicate with an AT24C02 EEPROM chip on a circuit board, with an address of 50 hex and a board index of 0, using the Aardvark adapter.

Ensure that the Aardvark adapter is installed so that you can use the i2c interface, and then view the adapter properties.

instrhwinfo('i2c')
instrhwinfo('i2c','Aardvark')
ans = 

  HardwareInfo with properties:

    InstalledAdaptors: {'Aardvark'  'NI845x'}
       JarFileVersion: 'Version 4.1'

Access to your hardware may be provided by a support package. Go to the Support Package Installer to learn more.



ans = 

  HardwareInfo with properties:

             AdaptorDllName: 'C:\Program Files\MATLAB\R2019b\toolbox\instrument\instrumentadaptors\win64\mwaardvarki2c.dll'
          AdaptorDllVersion: 'Version 4.1'
                AdaptorName: 'Aardvark'
              BoardIdsInUse: [1×0 double]
          InstalledBoardIDs: 0
       DetectedBoardSerials: {'2237482577 (BoardIndex: 0)'}
      ObjectConstructorName: 'i2c('Aardvark', BoardIndex, RemoteAddress);'
              VendorDllName: 'aardvark.dll'
    VendorDriverDescription: 'Total Phase I2C Driver'

Access to your hardware may be provided by a support package. Go to the Support Package Installer to learn more.

Create an i2c object named i2cobj with the Vendor 'Aardvark', BoardIndex of 0, and RemoteAddress of 50h.

i2cobj = i2c('Aardvark',0,'50h')
   I2C Object : I2C-0-50h

   Communication Settings 
      BoardIndex          0
      BoardSerial         0
      BitRate:            100 kHz
      RemoteAddress:      50h
      Vendor:             aardvark


   Communication State 
      Status:             closed
      RecordStatus:       off

   Read/Write State  
      TransferStatus:     idle

Connect to the chip.

fopen(i2cobj)

Note

If Target Power is off in the Total Phase Control Center Serial Software, you might receive an error when you try to connect to the Aardvark adapter using fopen. To manually set the option, open the software and select the Target Power check box.

Write 'Hello World!' to the EEPROM chip. Data is written page-by-page in I2C. Each page contains eight bytes. The page address needs to be mentioned before every byte of data written.

The first byte of the string 'Hello World!' is 'Hello Wo'. Its page address is 0.

fwrite(i2cobj,[0 'Hello Wo'])

The second byte of the string 'Hello World!' is 'rld!'. Its page address is 8.

fwrite(i2cobj,[8 'rld!'])

To start reading from the first byte of the first page, write a zero to the i2c object.

fwrite(i2cobj,0)

Read data back from the chip using the fread function. The chip returns the characters sent to it.

char(fread(i2cobj,12))'
ans =

    'Hello World!'

Disconnect the I2C device.

fclose(i2cobj)

Clear the object from the workspace.

clear i2cobj

Communicate with multiple I2C peripheral devices from the same NI USB-845x adapter. You can read from multiple peripheral devices using the Aardvark adapter as well. In this example, the two peripheral devices are two sensor chips on a circuit board, with addresses of 62 hex and 53 hex. The board index is 0. The NI USB-845x adapter board is plugged into the computer (via the USB port), and a circuit board containing the sensor chips is connected to the host adapter board via wires.

Ensure that the NI USB-845x adapter is installed so that you can use the i2c interface, and then view the adapter properties.

instrhwinfo('i2c')
instrhwinfo('i2c','NI845x')
ans = 

  HardwareInfo with properties:

    InstalledAdaptors: {'Aardvark'  'NI845x'}
       JarFileVersion: 'Version 4.1'

Access to your hardware may be provided by a support package. Go to the Support Package Installer to learn more.



ans = 

  HardwareInfo with properties:

             AdaptorDllName: 'C:\Program Files\MATLAB\R2019b\toolbox\instrument\instrumentadaptors\win64\mwni845xi2c.dll'
          AdaptorDllVersion: 'Version 4.1'
                AdaptorName: 'NI845x'
              BoardIdsInUse: [1×0 double]
          InstalledBoardIDs: [1×0 double]
       DetectedBoardSerials: {0×1 cell}
      ObjectConstructorName: 'i2c('NI845x', BoardIndex, RemoteAddress);'
              VendorDllName: 'Ni845x.dll'
    VendorDriverDescription: 'National Instruments NI USB 845x Driver'

Access to your hardware may be provided by a support package. Go to the Support Package Installer to learn more.

Create an i2c object named i2cobj with the Vendor 'NI845x', BoardIndex of 0, and RemoteAddress of 62h. This address is the remote address of the first I2C peripheral device to which you connect.

i2cobj = i2c('NI845x',0,'62h')
   I2C Object : I2C-0-62h

   Communication Settings 
      BoardIndex          0
      BoardSerial         0
      BitRate:            100 kHz
      RemoteAddress:      62h
      Vendor:             NI845x


   Communication State 
      Status:             closed
      RecordStatus:       off

   Read/Write State  
      TransferStatus:     idle

Open a connection to the NI USB-845x adapter. This connection is to the sensor chip with the RemoteAddress specified during object creation.

fopen(i2cobj)

Write to the sensor chip. You need to read the documentation or data sheet of the chip to find the remote address and other information about the chip. In this case, open the chip registry by sending it a 0.

fwrite(i2cobj,0)

Read data back from the chip using the fread function. By sending one byte, you can read back the device ID registry. For this chip, the read-only device ID registry is 229.

fread(i2cobj,1)
ans = 

   229

Switch to the second sensor chip by setting the RemoteAddress to 53h. This address is the remote address of the second I2C peripheral device to which you connect. You do not need to reopen a connection with the adapter.

i2cobj.RemoteAddress = '53h';

Write to and read from the sensor chip. Because this chip is identical to the first chip, its device ID registry is also 229.

fwrite(i2cobj,0)
fread(i2cobj,1)

ans = 

   229

Disconnect the I2C device.

fclose(i2cobj)

Clear the object from the workspace.

clear i2cobj

See Also

Topics

Introduced in R2012a

Instrument Control Toolbox Documentation

Support