The I2C API provides functions to control I2C peripherals connected to the IoT device.

The I2C API provides access to peripherals using the I2C protocol.

Required Header

#include <peripheral_io.h>

Overview

This I2C API provides support for I2C-based communication. While the I2C protocal can handle many devices connected to a single bus, this API requires one peripheral_spi_h object for each device. Unlike SPI and CAPI_SYSTEM_PERIPHERAL_IO_UART_MODULE protocols, this does not require preconfiguration. Additionally, instead of reading and writing arbitrary data, it structures the data using registers, so the API is rather different.

Related Features

This API is related with the following feature:

http://tizen.org/feature/peripheral_io.i2c

It is recommended to use features in your application for reliability.

You can check if a IoT device supports the related features for this API
by using System Information, and control your application's actions accordingly.

To ensure your application is only running on the IoT device with specific features,
please define the features in your manifest file using the manifest editor in the SDK.

More details on featuring your application can be found from Feature Element.

Functions
int	peripheral_i2c_open (int bus, int address, peripheral_i2c_h *i2c)
	Opens an I2C slave device and returns a handle representing it.
int	peripheral_i2c_open_flags (int bus, int address, peripheral_open_flags_e flags, peripheral_i2c_h *i2c)
	Opens an I2C slave device and returns a representing handle.
int	peripheral_i2c_close (peripheral_i2c_h i2c)
	Closes an I2C slave device and frees resources associated with the handle.
int	peripheral_i2c_read (peripheral_i2c_h i2c, uint8_t *data, uint32_t length)
	Reads the bytes data from the I2C slave device into a buffer.
int	peripheral_i2c_write (peripheral_i2c_h i2c, uint8_t *data, uint32_t length)
	Writes the bytes data from a buffer to the I2C slave device.
int	peripheral_i2c_read_register_byte (peripheral_i2c_h i2c, uint8_t reg, uint8_t *data)
	Reads byte data from the register of the I2C slave device.
int	peripheral_i2c_write_register_byte (peripheral_i2c_h i2c, uint8_t reg, uint8_t data)
	Writes byte data to the register of the I2C slave device.
int	peripheral_i2c_read_register_word (peripheral_i2c_h i2c, uint8_t reg, uint16_t *data)
	Reads word data from the register of the I2C slave device.
int	peripheral_i2c_write_register_word (peripheral_i2c_h i2c, uint8_t reg, uint16_t data)
	Writes word data to the register of the I2C slave device.
Typedefs
typedef struct _peripheral_i2c_s *	peripheral_i2c_h
	An opaque handle representing the I2C slave device.

Typedef Documentation

typedef struct _peripheral_i2c_s* peripheral_i2c_h

An opaque handle representing the I2C slave device.

A handle to a single I2C slave device, for use with most I2C slave interfaces

Since :: 4.0

Enumeration Type Documentation

enum peripheral_open_flags_e

Enumeration for open flags (bitmask) for an i2c device.

Since :: 6.5

Enum values are supposed to be used as bitmask, where only one value can be specified for following flag groups:

locking mode - either PERIPHERAL_OPEN_FLAGS_PRIVATE or PERIPHERAL_OPEN_FLAGS_SHARED can be used

The PERIPHERAL_OPEN_FLAGS_NONBLOCK can be used with all other available flags.

Enumerator:

PERIPHERAL_OPEN_FLAGS_PRIVATE	Exclusive access to device
PERIPHERAL_OPEN_FLAGS_SHARED	Shared access to device
PERIPHERAL_OPEN_FLAGS_NONBLOCK	Nonblocking read/write flag, available for only uart (Since 8.0)

Function Documentation

int peripheral_i2c_close ( peripheral_i2c_h i2c )

Closes an I2C slave device and frees resources associated with the handle.

Warning:: This is not for use by third-party applications.

This function should be called at the end of the object's lifetime to avoid a memory leak.

Since :: 4.0

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/peripheralio

Parameters:

[in] i2c The I2C handle

Returns:: 0 on success, otherwise a negative error value

Return values:

PERIPHERAL_ERROR_NONE	Successful
PERIPHERAL_ERROR_NOT_SUPPORTED	Not supported
PERIPHERAL_ERROR_PERMISSION_DENIED	Permission denied
PERIPHERAL_ERROR_INVALID_PARAMETER	Invalid parameter
PERIPHERAL_ERROR_UNKNOWN	Unknown internal error

Precondition:: peripheral_i2c_open()

#include <peripheral_io.h>

#define I2C_BUS 1
#define I2C_ADDRESS 0x07

int main(void)
{
    int ret;
    peripheral_i2c_h i2c;

    ret = peripheral_i2c_open(I2C_BUS, I2C_ADDRESS, &i2c);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);

    // Use the connection here

    ret = peripheral_i2c_close(i2c);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);
}

int peripheral_i2c_open	(	int	bus,
		int	address,
		peripheral_i2c_h *	i2c
	)

Opens an I2C slave device and returns a handle representing it.

Warning:: This is not for use by third-party applications.

Starts the lifetime of the handle and allocates its needed resources.

Since :: 4.0

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/peripheralio

Remarks:: i2c should be released with peripheral_i2c_close()

Parameters:

[in]	bus	The I2C bus number that the slave device is connected
[in]	address	The address of the slave device
[out]	i2c	The I2C handle is created on success

Returns:: 0 on success, otherwise a negative error value

Return values:

PERIPHERAL_ERROR_NONE	Successful
PERIPHERAL_ERROR_NOT_SUPPORTED	Not supported
PERIPHERAL_ERROR_PERMISSION_DENIED	Permission denied
PERIPHERAL_ERROR_INVALID_PARAMETER	Invalid parameter
PERIPHERAL_ERROR_IO_ERROR	I/O operation failed
PERIPHERAL_ERROR_NO_DEVICE	Device does not exist or is removed
PERIPHERAL_ERROR_OUT_OF_MEMORY	Memory allocation failed
PERIPHERAL_ERROR_RESOURCE_BUSY	Device is in use
PERIPHERAL_ERROR_UNKNOWN	Unknown internal error

Postcondition:: peripheral_i2c_close()

#include <peripheral_io.h>

#define I2C_BUS 1
#define I2C_ADDRESS 0x07

int main(void)
{
    int ret;
    peripheral_i2c_h i2c;

    ret = peripheral_i2c_open(I2C_BUS, I2C_ADDRESS, &i2c);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);

    // Use the connection here

    ret = peripheral_i2c_close(i2c);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);
}

int peripheral_i2c_open_flags	(	int	bus,
		int	address,
		peripheral_open_flags_e	flags,
		peripheral_i2c_h *	i2c
	)

Opens an I2C slave device and returns a representing handle.

Warning:: This is not for use by third-party applications.

Starts the lifetime of the handle and allocates its needed resources.

Since :: 6.5

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/peripheralio

Remarks:: i2c should be released with peripheral_i2c_close()

Parameters:

[in]	bus	The I2C bus number that the slave device is connected
[in]	address	The address of the slave device
[in]	flags	The flags to open call
[out]	i2c	The I2C handle is created on success

Returns:: 0 on success, otherwise a negative error value

Return values:

PERIPHERAL_ERROR_NONE	Successful
PERIPHERAL_ERROR_NOT_SUPPORTED	Not supported
PERIPHERAL_ERROR_PERMISSION_DENIED	Permission denied
PERIPHERAL_ERROR_INVALID_PARAMETER	Invalid parameter
PERIPHERAL_ERROR_IO_ERROR	I/O operation failed
PERIPHERAL_ERROR_NO_DEVICE	Device does not exist or is removed
PERIPHERAL_ERROR_OUT_OF_MEMORY	Memory allocation failed
PERIPHERAL_ERROR_RESOURCE_BUSY	Device is in use
PERIPHERAL_ERROR_UNKNOWN	Unknown internal error

Postcondition:: peripheral_i2c_close()

#include <peripheral_io.h>

#define I2C_BUS 1
#define I2C_ADDRESS 0x07

int main(void)
{
    int ret;
    peripheral_i2c_h i2c;

    ret = peripheral_i2c_open_flags(I2C_BUS, I2C_ADDRESS,
        PERIPHERAL_OPEN_FLAGS_SHARED | PERIPHERAL_OPEN_FLAGS_NONBLOCK,
        &i2c);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);

    // Use the connection here

    ret = peripheral_i2c_close(i2c);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);
}

int peripheral_i2c_read	(	peripheral_i2c_h	i2c,
		uint8_t *	data,
		uint32_t	length
	)

Reads the bytes data from the I2C slave device into a buffer.

Warning:: This is not for use by third-party applications.

Fills the buffer with data read from the provided device.

Since :: 4.0

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/peripheralio

Parameters:

[in]	i2c	The I2C handle
[out]	data	The data buffer to read
[in]	length	The size of data buffer (in bytes)

Returns:: 0 on success, otherwise a negative error value

Return values:

PERIPHERAL_ERROR_NONE	Successful
PERIPHERAL_ERROR_NOT_SUPPORTED	Not supported
PERIPHERAL_ERROR_PERMISSION_DENIED	Permission denied
PERIPHERAL_ERROR_INVALID_PARAMETER	Invalid parameter
PERIPHERAL_ERROR_IO_ERROR	I/O operation failed
PERIPHERAL_ERROR_UNKNOWN	Unknown internal error

See also:: peripheral_i2c_write()

#include <peripheral_io.h>
#include <stdio.h>

#define READ_SIZE 4

void read_bytes(peripheral_i2c_h i2c)
{
    int ret;
    uint8_t data[READ_SIZE];

    ret = peripheral_i2c_read(i2c, data, READ_SIZE);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);

    for (int i = 0; i < BUFFER_SIZE; ++i)
        printf("%02x", data[i]);
}

int peripheral_i2c_read_register_byte	(	peripheral_i2c_h	i2c,
		uint8_t	reg,
		uint8_t *	data
	)

Reads byte data from the register of the I2C slave device.

Warning:: This is not for use by third-party applications.

Will only read a single byte from the provided register.

Since :: 4.0

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/peripheralio

Parameters:

[in]	i2c	The I2C handle
[in]	reg	The register address of the I2C slave device to read
[out]	data	The single byte data to read

Returns:: 0 on success, otherwise a negative error value

Return values:

PERIPHERAL_ERROR_NONE	Successful
PERIPHERAL_ERROR_NOT_SUPPORTED	Not supported
PERIPHERAL_ERROR_PERMISSION_DENIED	Permission denied
PERIPHERAL_ERROR_INVALID_PARAMETER	Invalid parameter
PERIPHERAL_ERROR_IO_ERROR	I/O operation failed
PERIPHERAL_ERROR_UNKNOWN	Unknown internal error

See also:: peripheral_i2c_write_register_byte()

#include <peripheral_io.h>
#include <stdio.h>

#define REGISTER 0x7

void read_byte(peripheral_i2c_h i2c)
{
    int ret;
    uint8_t data;

    ret = peripheral_i2c_read_register_byte(i2c, REGISTER, &data);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);

    printf("%02x", data);
}

int peripheral_i2c_read_register_word	(	peripheral_i2c_h	i2c,
		uint8_t	reg,
		uint16_t *	data
	)

Reads word data from the register of the I2C slave device.

Warning:: This is not for use by third-party applications.

Will read two bytes (a word) from the provided register.

Since :: 4.0

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/peripheralio

Parameters:

[in]	i2c	The I2C handle
[in]	reg	The register address of the I2C slave device to read
[out]	data	The word(2 bytes) data to read

Returns:: 0 on success, otherwise a negative error value

Return values:

PERIPHERAL_ERROR_NONE	Successful
PERIPHERAL_ERROR_NOT_SUPPORTED	Not supported
PERIPHERAL_ERROR_PERMISSION_DENIED	Permission denied
PERIPHERAL_ERROR_INVALID_PARAMETER	Invalid parameter
PERIPHERAL_ERROR_IO_ERROR	I/O operation failed
PERIPHERAL_ERROR_UNKNOWN	Unknown internal error

See also:: peripheral_i2c_write_register_word()

#include <peripheral_io.h>
#include <stdio.h>

#define REGISTER 0x7

void read_word(peripheral_i2c_h i2c)
{
    int ret;
    uint16_t data;

    ret = peripheral_i2c_read_register_word(i2c, REGISTER, &data);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);

    printf("%04x", data);
}

int peripheral_i2c_write	(	peripheral_i2c_h	i2c,
		uint8_t *	data,
		uint32_t	length
	)

Writes the bytes data from a buffer to the I2C slave device.

Warning:: This is not for use by third-party applications.

Reads the data from the buffer and sends it into the device.

Since :: 4.0

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/peripheralio

Parameters:

[in]	i2c	The I2C handle
[in]	data	The data buffer to write
[in]	length	The size of data buffer (in bytes)

Returns:: 0 on success, otherwise a negative error value

Return values:

PERIPHERAL_ERROR_NONE	Successful
PERIPHERAL_ERROR_NOT_SUPPORTED	Not supported
PERIPHERAL_ERROR_PERMISSION_DENIED	Permission denied
PERIPHERAL_ERROR_INVALID_PARAMETER	Invalid parameter
PERIPHERAL_ERROR_IO_ERROR	I/O operation failed
PERIPHERAL_ERROR_UNKNOWN	Unknown internal error

See also:: peripheral_i2c_read()

#include <peripheral_io.h>

static uint8_t data_to_write[] = { 0x1, 0x2, 0x3, 0x4 };

void write_bytes(peripheral_i2c_h i2c)
{
    int ret;

    ret = peripheral_i2c_write(i2c, data_to_write,
        sizeof(data_to_write) / sizeof(data_to_write[0]));
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);
}

int peripheral_i2c_write_register_byte	(	peripheral_i2c_h	i2c,
		uint8_t	reg,
		uint8_t	data
	)

Writes byte data to the register of the I2C slave device.

Warning:: This is not for use by third-party applications.

Will only write a single byte to the provided register.

Since :: 4.0

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/peripheralio

Parameters:

[in]	i2c	The I2C handle
[in]	reg	The register address of the I2C slave device to write
[in]	data	The single byte data to write

Returns:: 0 on success, otherwise a negative error value

Return values:

PERIPHERAL_ERROR_NONE	Successful
PERIPHERAL_ERROR_NOT_SUPPORTED	Not supported
PERIPHERAL_ERROR_PERMISSION_DENIED	Permission denied
PERIPHERAL_ERROR_INVALID_PARAMETER	Invalid parameter
PERIPHERAL_ERROR_IO_ERROR	I/O operation failed
PERIPHERAL_ERROR_UNKNOWN	Unknown internal error

See also:: peripheral_i2c_read_register_byte()

#include <peripheral_io.h>

#define REGISTER 0x7
#define DATA 0x11

void write_byte(peripheral_i2c_h i2c)
{
    int ret;

    ret = peripheral_i2c_write_register_byte(i2c, REGISTER, DATA);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);
}

int peripheral_i2c_write_register_word	(	peripheral_i2c_h	i2c,
		uint8_t	reg,
		uint16_t	data
	)

Writes word data to the register of the I2C slave device.

Warning:: This is not for use by third-party applications.

Will write two bytes (a word) to the provided register.

Since :: 4.0

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/peripheralio

Parameters:

[in]	i2c	The I2C handle
[in]	reg	The register address of the I2C slave device to write
[in]	data	The word(2 bytes) data to write

Returns:: 0 on success, otherwise a negative error value

Return values:

PERIPHERAL_ERROR_NONE	Successful
PERIPHERAL_ERROR_NOT_SUPPORTED	Not supported
PERIPHERAL_ERROR_PERMISSION_DENIED	Permission denied
PERIPHERAL_ERROR_INVALID_PARAMETER	Invalid parameter
PERIPHERAL_ERROR_IO_ERROR	I/O operation failed
PERIPHERAL_ERROR_UNKNOWN	Unknown internal error

See also:: peripheral_i2c_read_register_word()

#include <peripheral_io.h>

#define REGISTER 0x7
#define DATA 0x1234

void write_word(peripheral_i2c_h i2c)
{
    int ret;

    ret = peripheral_i2c_write_register_word(i2c, REGISTER, DATA);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);
}

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation