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

The GPIO API provides access to simple GPIO peripherals.

Required Header

#include <peripheral_io.h>

Overview

This GPIO API provides access to simple GPIO peripherals. It can be used to set a single pin high or low, to read the current value of this pin, or to track changes of the pin value using interrupts.

Related Features

This API is related with the following feature:

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

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_gpio_open (int gpio_pin, peripheral_gpio_h *gpio)
	Opens a GPIO pin and returns a handle representing it.
int	peripheral_gpio_close (peripheral_gpio_h gpio)
	Closes a GPIO pin and frees the resources associated with the handle.
int	peripheral_gpio_set_direction (peripheral_gpio_h gpio, peripheral_gpio_direction_e direction)
	Sets the input/output direction of given GPIO pin.
int	peripheral_gpio_set_edge_mode (peripheral_gpio_h gpio, peripheral_gpio_edge_e edge)
	Sets the input edge mode of given GPIO pin device.
int	peripheral_gpio_set_interrupted_cb (peripheral_gpio_h gpio, peripheral_gpio_interrupted_cb callback, void *user_data)
	Sets the GPIO interrupted callback to the provided function.
int	peripheral_gpio_unset_interrupted_cb (peripheral_gpio_h gpio)
	Unsets the previously set GPIO interrupted callback.
int	peripheral_gpio_read (peripheral_gpio_h gpio, uint32_t *value)
	Gets the current value being exposed on the GPIO pin.
int	peripheral_gpio_write (peripheral_gpio_h gpio, uint32_t value)
	Sets the value to be exposed on the given GPIO pin.
Typedefs
typedef struct _peripheral_gpio_s *	peripheral_gpio_h
	An opaque handle to an object representing a GPIO pin.
typedef void(*	peripheral_gpio_interrupted_cb )(peripheral_gpio_h gpio, peripheral_error_e error, void *user_data)
	The GPIO interrupted callback called when the GPIO interrupt is triggered.

Typedef Documentation

typedef struct _peripheral_gpio_s* peripheral_gpio_h

An opaque handle to an object representing a GPIO pin.

A handle to a single GPIO pin, for use with most GPIO interfaces

Since :: 4.0

typedef void(* peripheral_gpio_interrupted_cb)(peripheral_gpio_h gpio, peripheral_error_e error, void *user_data)

The GPIO interrupted callback called when the GPIO interrupt is triggered.

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

The following errors can be received:
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_TRY_AGAIN Try again
PERIPHERAL_ERROR_OUT_OF_MEMORY Memory allocation failed
PERIPHERAL_ERROR_RESOURCE_BUSY Device is in use
PERIPHERAL_ERROR_UNKNOWN Unknown internal error

Since :: 4.0

Parameters:

[in]	gpio	The GPIO handle
[in]	error	The GPIO error
[in]	user_data	The user data passed from the callback registration function

See also:: peripheral_gpio_set_interrupted_cb()

Enumeration Type Documentation

enum peripheral_gpio_direction_e

Enumeration representing GPIO device direction options.

Some interfaces require you to specify whether data goes in or out.

Since :: 4.0

Enumerator:

PERIPHERAL_GPIO_DIRECTION_IN	Input Mode
PERIPHERAL_GPIO_DIRECTION_OUT_INITIALLY_HIGH	Output mode with high value
PERIPHERAL_GPIO_DIRECTION_OUT_INITIALLY_LOW	Output mode with low value

enum peripheral_gpio_edge_e

Enumeration for edge types for the GPIO interrupt.

Some interfaces require you to specify what kind of signal edge produces an interrupt.

Since :: 4.0

Enumerator:

PERIPHERAL_GPIO_EDGE_NONE	No interrupt on GPIO
PERIPHERAL_GPIO_EDGE_RISING	Interrupt on rising only
PERIPHERAL_GPIO_EDGE_FALLING	Interrupt on falling only
PERIPHERAL_GPIO_EDGE_BOTH	Interrupt on rising & falling

Function Documentation

int peripheral_gpio_close ( peripheral_gpio_h gpio )

Closes a GPIO pin and frees the 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] gpio The GPIO 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

Precondition:: peripheral_gpio_open()

#include <peripheral_io.h>

#define PIN_NUMBER 7

int main(void)
{
    int ret;
    peripheral_gpio_h gpio;

    ret = peripheral_gpio_open(PIN_NUMBER, &gpio);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);

    // Use the pin here

    ret = peripheral_gpio_close(gpio);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);
}

int peripheral_gpio_open	(	int	gpio_pin,
		peripheral_gpio_h *	gpio
	)

Opens a GPIO pin 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:: gpio should be released with peripheral_gpio_close()

Parameters:

[in]	gpio_pin	The GPIO pin number
[out]	gpio	The GPIO 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_gpio_close()

#include <peripheral_io.h>

#define PIN_NUMBER 7

int main(void)
{
    int ret;
    peripheral_gpio_h gpio;

    ret = peripheral_gpio_open(PIN_NUMBER, &gpio);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);

    // Use the pin here

    ret = peripheral_gpio_close(gpio);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);
}

int peripheral_gpio_read	(	peripheral_gpio_h	gpio,
		uint32_t *	value
	)

Gets the current value being exposed on the GPIO pin.

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

Reads data from the GPIO pin to the specified address.

Since :: 4.0

Privilege Level:: platform

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

Parameters:

[in]	gpio	The GPIO handle
[out]	value	The value to get

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_gpio_write()

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

gboolean loop_iteration(gpointer user_data)
{
    peripheral_gpio_h gpio = user_data;
    int ret;
    uint32_t data;

    ret = peripheral_gpio_read(gpio, &data);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);

    printf("Current GPIO pin value: %d\n", (int)data);

    return G_SOURCE_CONTINUE;
}

guint read_in_a_loop(peripheral_gpio_h gpio)
{
    int ret = peripheral_gpio_set_direction(gpio, PERIPHERAL_GPIO_DIRECTION_IN);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);

    return g_timeout_add_seconds(1, loop_iteration, gpio);
}

int peripheral_gpio_set_direction	(	peripheral_gpio_h	gpio,
		peripheral_gpio_direction_e	direction
	)

Sets the input/output direction of given GPIO pin.

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

Sets whether data goes in or out on given GPIO pin.

Since :: 4.0

Privilege Level:: platform

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

Remarks:: To set the direction to PERIPHERAL_GPIO_DIRECTION_OUT_INITIALLY_HIGH or PERIPHERAL_GPIO_DIRECTION_OUT_INITIALLY_LOW, the edge mode must be set to PERIPHERAL_GPIO_EDGE_NONE.

Parameters:

[in]	gpio	The GPIO handle
[in]	direction	The direction of the GPIO pin

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_gpio_direction_e; peripheral_gpio_set_edge_mode()

#include <peripheral_io.h>

void configure_pin(peripheral_gpio_h gpio, bool input_needed, bool output_needed)
{
    int ret;

    if (input_needed)
        ret = peripheral_gpio_set_direction(gpio, PERIPHERAL_GPIO_DIRECTION_IN);
    else if (output_needed)
        ret = peripheral_gpio_set_direction(gpio, PERIPHERAL_GPIO_DIRECTION_OUT_INITIALLY_LOW);
    else
        handle_this_case();

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

int peripheral_gpio_set_edge_mode	(	peripheral_gpio_h	gpio,
		peripheral_gpio_edge_e	edge
	)

Sets the input edge mode of given GPIO pin device.

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

Changes which kind of edges will trigger the GPIO interrupts.

Since :: 4.0

Privilege Level:: platform

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

Remarks:: To set the edge mode to PERIPHERAL_GPIO_EDGE_RISING, PERIPHERAL_GPIO_EDGE_FALLING, PERIPHERAL_GPIO_EDGE_BOTH, the data direction must be set to the PERIPHERAL_GPIO_DIRECTION_IN.

Parameters:

[in]	gpio	The GPIO handle
[in]	edge	The edge mode of the GPIO pin

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_gpio_edge_e; peripheral_gpio_set_direction()

#include <peripheral_io.h>

void configure_pin(peripheral_gpio_h gpio, bool on_rising, bool on_falling)
{
    int ret = peripheral_gpio_set_direction(gpio, PERIPHERAL_GPIO_DIRECTION_IN);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);

    if (on_rising) {
        if (on_falling)
            ret = peripheral_gpio_set_edge_mode(gpio, PERIPHERAL_GPIO_EDGE_BOTH);
        else
            ret = peripheral_gpio_set_edge_mode(gpio, PERIPHERAL_GPIO_EDGE_RISING);
    } else {
        if (on_falling)
            ret = peripheral_gpio_set_edge_mode(gpio, PERIPHERAL_GPIO_EDGE_FALLING);
        else
            ret = peripheral_gpio_set_edge_mode(gpio, PERIPHERAL_GPIO_EDGE_NONE);
    }
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);
}

int peripheral_gpio_set_interrupted_cb	(	peripheral_gpio_h	gpio,
		peripheral_gpio_interrupted_cb	callback,
		void *	user_data
	)

Sets the GPIO interrupted callback to the provided function.

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

The callback will be called when the GPIO interrupt is triggered.

Since :: 4.0

Privilege Level:: platform

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

Remarks:: The interrupted callback is unset when peripheral_gpio_unset_interrupted_cb() is called, when another callback is registered for the same peripheral_gpio_h handle (it is not possible to have multiple callbacks at the same time) or when callback receives an error value other than PERIPHERAL_ERROR_NONE. Additionally, the callback cannot modify the provided gpio handle in anyway, it should consider it read-only.

Parameters:

[in]	gpio	The GPIO handle
[in]	callback	The GPIO interrupted callback function to set
[in]	user_data	The user data to be passed to the callback function

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_OUT_OF_MEMORY	Memory allocation failed

Postcondition:: peripheral_gpio_unset_interrupted_cb()

See also:: peripheral_gpio_set_edge_mode()

#include <peripheral_io.h>

void callback(peripheral_gpio_h gpio, peripheral_error_e error, void *user_data)
{
    struct our_data_type *callback_data = user_data;
    int ret;
    uint32_t pin_value;

    if (error != PERIPHERAL_ERROR_NONE)
        handle_error(error);

    ret = peripheral_gpio_read(gpio, &pin_value);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);

    process_value(callback_data, pin_value);
}

void set_callback(peripheral_gpio_h gpio)
{
    struct our_data_type *callback_data = create_callback_data();

    int ret = peripheral_gpio_set_interrupted_cb(gpio, callback, callback_data);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);
}

int peripheral_gpio_unset_interrupted_cb ( peripheral_gpio_h gpio )

Unsets the previously set GPIO interrupted callback.

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

The callback will no longer be invoked when the GPIO interrupt is triggered.

Since :: 4.0

Privilege Level:: platform

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

Remarks:: If there is no callback registered, the function will be successful anyway, so it's ok to call it unconditionally regardless of peripheral_gpio_set_interrupted_cb() success. After this function exits, the callback will not be called anymore.

Parameters:

[in] gpio The GPIO 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

Precondition:: peripheral_gpio_set_interrupted_cb()

#include <peripheral_io.h>

void unset_callback(peripheral_gpio_h gpio, struct our_data_type *callback_data)
{
    int ret = peripheral_gpio_unset_interrupted_cb(gpio);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);

    // Make sure the callback is not running in parallel!
    // The callback will run on the GLib main context,
    // if you are also running this on the main context too,
    // which is probably the case if your app is single-threaded,
    // it is ok to immediately deallocate.
    destroy_callback_data(callback_data);
}

int peripheral_gpio_write	(	peripheral_gpio_h	gpio,
		uint32_t	value
	)

Sets the value to be exposed on the given GPIO pin.

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

Writes data into the GPIO pin from the specified address.

Since :: 4.0

Privilege Level:: platform

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

Remarks:: To write binary data, the direction must be set to PERIPHERAL_GPIO_DIRECTION_OUT_INITIALLY_HIGH or PERIPHERAL_GPIO_DIRECTION_OUT_INITIALLY_LOW.

Parameters:

[in]	gpio	The GPIO handle
[in]	value	The value to set (must be 0 or 1)

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_gpio_read(); peripheral_gpio_set_direction()

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

gboolean loop_iteration(gpointer user_data)
{
    peripheral_gpio_h gpio = user_data;
    int ret;

    ret = peripheral_gpio_write(gpio, g_random_int_range(0, 2));
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);

    printf("Current GPIO pin value: %d\n", (int)data);

    return G_SOURCE_CONTINUE;
}

guint read_in_a_loop(peripheral_gpio_h gpio)
{
    int ret = peripheral_gpio_set_direction(gpio, PERIPHERAL_GPIO_DIRECTION_OUT_INITIALLY_LOW);
    if (ret != PERIPHERAL_ERROR_NONE)
        handle_error(ret);

    return g_timeout_add_seconds(1, loop_iteration, gpio);
}

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation