GPIO

The GPIO API provides access to General Purpose Input/Output pins on Ocre containers. It enables applications to configure pins, read input states, set output states, and register callbacks for pin state changes.

---

Header File

To use the GPIO API in your application, include the ocre_api.h header from the Atym Toolchain, and link the ocre-sdk library when building your application.

#include "ocre_api.h"

Container Permissions

When using the GPIO API in your application, make sure to include the ocre_gpio permission in your build.yaml configuration file. This enables build-time validation to ensure your application only uses the GPIO functions you've declared.

config:
  permissions:
    - ocre_gpio

---

Execution Environment

Container applications shall use ocre_process_events() function to process their GPIO events. This is usually done in a loop, similar to following:

    // Main event loop - process events continuously
    while (1) {
        ocre_process_events();
    }

Types

GPIO Pin State

An enumeration defining the possible states of a GPIO pin.

typedef enum {
    OCRE_GPIO_PIN_RESET = 0,  ///< Pin is low (0)
    OCRE_GPIO_PIN_SET = 1     ///< Pin is high (1)
} ocre_gpio_pin_state_t;

GPIO Direction

An enumeration defining the direction of a GPIO pin.

typedef enum {
    OCRE_GPIO_DIR_INPUT = 0,   ///< Pin configured as input
    OCRE_GPIO_DIR_OUTPUT = 1   ///< Pin configured as output
} ocre_gpio_direction_t;

GPIO Callback Function

A function that will be called when a GPIO pin's state changes.

typedef void (*gpio_callback_func_t)(void);

---

Methods

GPIO Initialization

Initializes the GPIO subsystem. This function must be called before using any other GPIO functions.

int ocre_gpio_init(void);

Returns:

Value	Description
0	on success
negative value	on error

Configure GPIO Pin

Configures a GPIO pin for either input or output.

int ocre_gpio_configure(int port, int pin, int direction);

Parameters:

Name	Type	Description
port	int	GPIO port number
pin	int	GPIO pin number
direction	int	Direction to set for the pin (OCRE_GPIO_DIR_INPUT or OCRE_GPIO_DIR_OUTPUT)

Returns:

Value	Description
0	on success
negative value	on error

Set GPIO Pin

Sets the state of a GPIO output pin.

int ocre_gpio_pin_set(int port, int pin, ocre_gpio_pin_state_t state);

Parameters:

Name	Type	Description
port	int	GPIO port number
pin	int	GPIO pin number
state	ocre_gpio_pin_state_t	State to set the pin to (OCRE_GPIO_PIN_SET or OCRE_GPIO_PIN_RESET)

Returns:

Value	Description
0	on success
negative value	on error

Get GPIO Pin State

Reads the current state of a GPIO pin.

int ocre_gpio_pin_get(int port, int pin);

Parameters:

Name	Type	Description
port	int	GPIO port number
pin	int	GPIO pin number

Returns:

Value	Description
OCRE_GPIO_PIN_SET	if the pin is high
OCRE_GPIO_PIN_RESET	if the pin is low
negative value	on error

Toggle GPIO Pin

Toggles the state of a GPIO output pin.

int ocre_gpio_pin_toggle(int port, int pin);

Parameters:

Name	Type	Description
port	int	GPIO port number
pin	int	GPIO pin number

Returns:

Value	Description
0	on success
negative value	on error

Register GPIO Callback

Registers a callback function for GPIO pin state changes.

int ocre_register_gpio_callback(int pin, int port, gpio_callback_func_t callback);

Parameters:

Name	Type	Description
pin	int	GPIO pin number
port	int	GPIO port number
callback	gpio_callback_func_t	Callback function to register

Returns:

Value	Description
0	on success
negative value	on error

Unregister GPIO Callback

Removes a GPIO pin callback.

int ocre_unregister_gpio_callback(int pin, int port);

Parameters:

Name	Type	Description
pin	int	GPIO pin number
port	int	GPIO port number

Returns:

Value	Description
0	on success
negative value	on error

Configure GPIO Pin by Name

Configures a GPIO pin using its name instead of port/pin numbers.

int ocre_gpio_configure_by_name(const char *name, int direction);

Parameters:

Name	Type	Description
name	const char	GPIO pin name
direction	int	Direction to set for the pin (OCRE_GPIO_DIR_INPUT or OCRE_GPIO_DIR_OUTPUT)

Returns:

Value	Description
0	on success
negative value	on error

Set GPIO Pin by Name

Sets the state of a GPIO output pin using its name.

int ocre_gpio_set_by_name(const char *name, int state);

Parameters:

Name	Type	Description
name	const char	GPIO pin name
state	int	State to set the pin to (OCRE_GPIO_PIN_SET or OCRE_GPIO_PIN_RESET)

Returns:

Value	Description
0	on success
negative value	on error

Get GPIO Pin State by Name

Reads the current state of a GPIO pin using its name.

int ocre_gpio_get_by_name(const char *name);

Parameters:

Name	Type	Description
name	const char	GPIO pin name

Returns:

Value	Description
OCRE_GPIO_PIN_SET	if the pin is high
OCRE_GPIO_PIN_RESET	if the pin is low
negative value	on error

Toggle GPIO Pin by Name

Toggles the state of a GPIO output pin using its name.

int ocre_gpio_toggle_by_name(const char *name);

Parameters:

Name	Type	Description
name	const char	GPIO pin name

Returns:

Value	Description
0	on success
negative value	on error

Register GPIO Callback by Name

Registers a callback for GPIO pin state changes using the pin name.

int ocre_gpio_register_callback_by_name(const char *name);

Parameters:

Name	Type	Description
name	const char	GPIO pin name

Returns:

Value	Description
0	on success
negative value	on error

Unregister GPIO Callback by Name

Removes a GPIO pin callback using the pin name.

int ocre_gpio_unregister_callback_by_name(const char *name);

Parameters:

Name	Type	Description
name	const char	GPIO pin name

Returns:

Value	Description
0	on success
negative value	on error

---

Reference

Function	Description	Parameters	Return Value	Error Conditions
ocre_gpio_init	Initializes the GPIO subsystem	None	0: Success Negative: Error	System initialization failure
ocre_gpio_configure	Configures a GPIO pin	port: GPIO port number pin: GPIO pin number direction: Pin direction	0: Success Negative: Error	Invalid port/pin Pin already configured
ocre_gpio_pin_set	Sets GPIO pin state	port: GPIO port number pin: GPIO pin number state: Desired state	0: Success Negative: Error	Invalid port/pin Pin not configured as output
ocre_gpio_pin_get	Gets GPIO pin state	port: GPIO port number pin: GPIO pin number	Pin state Negative: Error	Invalid port/pin Pin not configured
ocre_gpio_pin_toggle	Toggles GPIO pin state	port: GPIO port number pin: GPIO pin number	0: Success Negative: Error	Invalid port/pin Pin not configured as output
ocre_register_gpio_callback	Registers pin change callback	pin: GPIO pin number port: GPIO port number callback: Callback function	0: Success Negative: Error	Invalid port/pin Callback limit reached
ocre_unregister_gpio_callback	Removes pin callback	pin: GPIO pin number port: GPIO port number	0: Success Negative: Error	Invalid port/pin No callback registered
ocre_gpio_configure_by_name	Configures a GPIO pin by name	name: GPIO pin name direction: Pin direction	0: Success Negative: Error	Invalid name Pin not found
ocre_gpio_set_by_name	Sets GPIO pin state by name	name: GPIO pin name state: Desired state	0: Success Negative: Error	Invalid name Pin not found
ocre_gpio_get_by_name	Gets GPIO pin state by name	name: GPIO pin name	Pin state Negative: Error	Invalid name Pin not found
ocre_gpio_toggle_by_name	Toggles GPIO pin state by name	name: GPIO pin name	0: Success Negative: Error	Invalid name Pin not found
ocre_gpio_register_callback_by_name	Registers callback by name	name: GPIO pin name	0: Success Negative: Error	Invalid name Pin not found
ocre_gpio_unregister_callback_by_name	Removes callback by name	name: GPIO pin name	0: Success Negative: Error	Invalid name No callback registered

---