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

The SPI API can be used to communicate using SPI.

Required Header

#include <peripheral_io.h>

Overview

This SPI API provides support for SPI-based communication. While the SPI protocal can handle many devices connected to a single bus, this API requires one peripheral_spi_h object for each device. This protocol requires several paramters to be preconfigured using peripheral_spi_set_* functions.

Related Features

This API is related with the following feature:

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

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_spi_open (int bus, int cs, peripheral_spi_h *spi)
	Opens a SPI slave device and returns a handle representing it.
int	peripheral_spi_close (peripheral_spi_h spi)
	Closes the SPI slave device and frees resources associated with the handle.
int	peripheral_spi_set_mode (peripheral_spi_h spi, peripheral_spi_mode_e mode)
	Sets the transfer mode for the given SPI slave device.
int	peripheral_spi_set_bit_order (peripheral_spi_h spi, peripheral_spi_bit_order_e bit_order)
	Sets the transfer bit order for given SPI slave device.
int	peripheral_spi_set_bits_per_word (peripheral_spi_h spi, uint8_t bits)
	Sets the number of bits per word for given SPI slave device.
int	peripheral_spi_set_frequency (peripheral_spi_h spi, uint32_t freq_hz)
	Sets the board-dependent frequency of the SPI bus.
int	peripheral_spi_read (peripheral_spi_h spi, uint8_t *data, uint32_t length)
	Reads the bytes data from the SPI slave device to a local buffer.
int	peripheral_spi_write (peripheral_spi_h spi, uint8_t *data, uint32_t length)
	Writes the bytes data buffer to the SPI slave device.
int	peripheral_spi_transfer (peripheral_spi_h spi, uint8_t txdata, uint8_t rxdata, uint32_t length)
	Exchanges (read and write) the bytes data to the SPI slave device.
Typedefs
typedef struct _peripheral_spi_s *	peripheral_spi_h
	An opaque handle representing a SPI peripherals slave device.

Typedef Documentation

typedef struct _peripheral_spi_s* peripheral_spi_h

An opaque handle representing a SPI peripherals slave device.

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

Since :: 4.0

Enumeration Type Documentation

enum peripheral_spi_bit_order_e

Enumeration of bit orders for SPI slave device interfaces.

Sets whether the most or the least significant bit goes first

Since :: 4.0

Enumerator:

PERIPHERAL_SPI_BIT_ORDER_MSB	Use most significant bit first
PERIPHERAL_SPI_BIT_ORDER_LSB	Use least significant bit first

enum peripheral_spi_mode_e

Enumeration of transfer modes for SPI slave devices.

Use this to control CPOL and CPHa modes on the device.

Since :: 4.0

Enumerator:

PERIPHERAL_SPI_MODE_0	CPOL = 0, CPHa = 0 Mode
PERIPHERAL_SPI_MODE_1	CPOL = 0, CPHa = 1 Mode
PERIPHERAL_SPI_MODE_2	CPOL = 1, CPHa = 0 Mode
PERIPHERAL_SPI_MODE_3	CPOL = 1, CPHa = 1 Mode

Function Documentation

int peripheral_spi_close ( peripheral_spi_h spi )

Closes the SPI 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] spi The SPI slave device 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_IO_ERROR	I/O operation failed
PERIPHERAL_ERROR_NO_DEVICE	Device does not exist or is removed
PERIPHERAL_ERROR_UNKNOWN	Unknown internal error

See also:: peripheral_spi_open()

#include <peripheral_io.h>

#define SPI_BUS 0
#define SPI_CS 1

int main(void)
{
    int ret;
    peripheral_spi_h spi;

    ret = peripheral_spi_open(SPI_BUS, SPI_CS, &spi);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);

    // Use the connection here

    ret = peripheral_spi_close(spi);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);
}

int peripheral_spi_open	(	int	bus,
		int	cs,
		peripheral_spi_h *	spi
	)

Opens a SPI 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:: spi should be released with peripheral_spi_close()

Parameters:

[in]	bus	The SPI bus number
[in]	cs	The SPI chip select number
[out]	spi	The SPI slave device 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_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_spi_close()

#include <peripheral_io.h>

#define SPI_BUS 0
#define SPI_CS 1

int main(void)
{
    int ret;
    peripheral_spi_h spi;

    ret = peripheral_spi_open(SPI_BUS, SPI_CS, &spi);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);

    // Use the connection here

    ret = peripheral_spi_close(spi);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);
}

int peripheral_spi_read	(	peripheral_spi_h	spi,
		uint8_t *	data,
		uint32_t	length
	)

Reads the bytes data from the SPI slave device to a local buffer.

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

Receives data into the specified buffer from the device.

Since :: 4.0

Privilege Level:: platform

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

Parameters:

[in]	spi	The SPI slave device 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_NO_DEVICE	Device does not exist or is removed
PERIPHERAL_ERROR_UNKNOWN	Unknown internal error

See also:: peripheral_spi_write()

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

#define BUFFER_SIZE 4

void print_spi_data(peripheral_spi_h spi)
{
    int ret;
    uint8_t data[BUFFER_SIZE];

    ret = peripheral_spi_read(spi, data, BUFFER_SIZE);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);

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

int peripheral_spi_set_bit_order	(	peripheral_spi_h	spi,
		peripheral_spi_bit_order_e	bit_order
	)

Sets the transfer bit order for given SPI slave device.

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

Allows to choose the transfer bit order expected by the device.

Since :: 4.0

Privilege Level:: platform

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

Remarks:: ARTIK530 and Raspberry Pi 3 do not support LSB first bit order.

Parameters:

[in]	spi	The SPI slave device handle
[in]	bit_order	The transfer bit order

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_UNKNOWN	Unknown internal error

See also:: peripheral_spi_bit_order_e

#include <peripheral_io.h>

void set_spi_msb(peripheral_spi_h spi)
{
    int ret = peripheral_spi_set_bit_order(spi, PERIPHERAL_SPI_BIT_ORDER_MSB);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);
}

int peripheral_spi_set_bits_per_word	(	peripheral_spi_h	spi,
		uint8_t	bits
	)

Sets the number of bits per word for given SPI slave device.

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

Allows to choose the number of bits per word expected by the device.

Since :: 4.0

Privilege Level:: platform

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

Parameters:

[in]	spi	The SPI slave device handle
[in]	bits	The number of bits per word (in bits)

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_UNKNOWN	Unknown internal error

#include <peripheral_io.h>

void set_spi_8_bits_per_word(peripheral_spi_h spi)
{
    int ret = peripheral_spi_set_bits_per_word(spi, 8);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);
}

int peripheral_spi_set_frequency	(	peripheral_spi_h	spi,
		uint32_t	freq_hz
	)

Sets the board-dependent frequency of the SPI bus.

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

Sets the frequency, in hertz, if the board supports it

Since :: 4.0

Privilege Level:: platform

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

Remarks:: The frequencies supported are board dependent.

Parameters:

[in]	spi	The SPI slave device handle
[in]	freq_hz	Frequency to set (in Hz)

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_UNKNOWN	Unknown internal error

#include <peripheral_io.h>

void set_spi_frequency(peripheral_spi_h spi)
{
    int ret = peripheral_spi_set_frequency(spi, 8000000);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);
}

int peripheral_spi_set_mode	(	peripheral_spi_h	spi,
		peripheral_spi_mode_e	mode
	)

Sets the transfer mode for the given SPI slave device.

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

Allows to choose the transfer mode expected by the device.

Since :: 4.0

Privilege Level:: platform

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

Parameters:

[in]	spi	The SPI slave device handle
[in]	mode	The SPI transfer mode

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_UNKNOWN	Unknown internal error

See also:: peripheral_spi_mode_e

#include <peripheral_io.h>

void set_spi_mode_0(peripheral_spi_h spi)
{
    int ret = peripheral_spi_set_mode(spi, PERIPHERAL_SPI_MODE_0);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);
}

int peripheral_spi_transfer	(	peripheral_spi_h	spi,
		uint8_t *	txdata,
		uint8_t *	rxdata,
		uint32_t	length
	)

Exchanges (read and write) the bytes data to the SPI slave device.

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

Performs data switcheroo. Essentially a combined write and read call.

Since :: 4.0

Privilege Level:: platform

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

Parameters:

[in]	spi	The SPI slave device handle
[in]	txdata	The data buffer to write
[out]	rxdata	The data buffer to read
[in]	length	The size of txdata and rxdata 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_NO_DEVICE	Device does not exist or is removed
PERIPHERAL_ERROR_UNKNOWN	Unknown internal error

See also:: peripheral_spi_read(); peripheral_spi_write()

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

static uint8_t data_to_write[] = { 0x1, 0x2, 0x3, 0x4 };
#define BUFFER_SIZE (sizeof(data_to_write) / sizeof(data_to_write[0]))

void transfer_bytes(peripheral_spi_h spi)
{
    int ret;
    uint8_t rxdata[BUFFER_SIZE];

    ret = peripheral_spi_transfer(spi, data_to_write, rxdata, BUFFER_SIZE);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);

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

int peripheral_spi_write	(	peripheral_spi_h	spi,
		uint8_t *	data,
		uint32_t	length
	)

Writes the bytes data buffer to the SPI slave device.

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

Puts data from the specified buffer unto the device.

Since :: 4.0

Privilege Level:: platform

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

Parameters:

[in]	spi	The SPI slave device 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_NO_DEVICE	Device does not exist or is removed
PERIPHERAL_ERROR_UNKNOWN	Unknown internal error

See also:: peripheral_spi_read()

#include <peripheral_io.h>

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

void write_bytes(peripheral_spi_h spi)
{
    int ret;

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

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation