GPIO (General Purpose Input Output)

group group_hal_gpio

High level interface for configuring and interacting with general purpose input/outputs (GPIO).

The GPIO driver provides functions to configure and initialize GPIO, and to read and write data to the pin. The driver also supports interrupt generation on GPIO signals with rising, falling or both edges.

note

The APIs in this driver need not be used if a GPIO is to be used as an input or output of peripherals like I2C or PWM. The respective peripheral's driver will utilize the GPIO interface to configure and initialize its GPIO pins.

Features

Quick Start

cyhal_gpio_init can be used for a simple GPIO initialization by providing the pin number (pin), pin direction (direction), pin drive mode (drive_mode) and the initial value on the pin (init_val).

Code Snippets

Snippet 1: Reading value from GPIO

The following snippet initializes GPIO pin as an input with high impedance digital drive mode and initial value = false (low). A value is read from the pin and stored to a uint8_t variable (read_val).

    cy_rslt_t rslt;
    bool      read_val;

    // Initialize pin P0_0 as an input
    rslt = cyhal_gpio_init(P0_0, CYHAL_GPIO_DIR_INPUT, CYHAL_GPIO_DRIVE_NONE, false);

    // Read the logic level on the input pin
    read_val = cyhal_gpio_read(P0_0);

Snippet 2: Writing value to a GPIO

The following snippet initializes GPIO pin as an output pin with strong drive mode and initial value = false (low). A value = true (high) is written to the output driver.

    cy_rslt_t rslt;
    bool      write_val = true;

    // Initialize pin P0_0 GPIO as an output with strong drive mode and initial value = false (low)
    rslt = cyhal_gpio_init(P0_0, CYHAL_GPIO_DIR_OUTPUT, CYHAL_GPIO_DRIVE_STRONG, false);

    // Write the value to the output pin
    cyhal_gpio_write(P0_0, write_val);

Snippet 3: Reconfiguring a GPIO

The following snippet shows how to reconfigure a GPIO pin during run-time using the firmware. The GPIO pin is first initialized as an output pin with strong drive mode. The pin is then reconfigured as an input with high impedance digital drive mode.

note

cyhal_gpio_configure only changes the direction and the drive_mode of the pin. Previously set pin value is retained.

    cy_rslt_t rslt;

    // Initialize pin P0_0 GPIO as an output with strong drive mode and initial value = false (low)
    rslt = cyhal_gpio_init(P0_0, CYHAL_GPIO_DIR_OUTPUT, CYHAL_GPIO_DRIVE_STRONG, false);

    // Application Code

    // Re-configure pin P0_0 as an input pin
    rslt = cyhal_gpio_configure(P0_0, CYHAL_GPIO_DIR_INPUT, CYHAL_GPIO_DRIVE_NONE);

Snippet 4: Interrupts on GPIO events

GPIO events can be mapped to an interrupt and assigned to a callback function. The callback function needs to be first registered and then the event needs to be enabled. The following snippet initializes GPIO pin as an input pin. It registers a callback function and enables detection of a falling edge event to trigger the callback.

note

If no argument needs to be passed to the callback function then a NULL can be passed during registering.

uint32_t global_count = 0;

// Interrupt handler callback function
void gpio_interrupt_handler(void* handler_arg, cyhal_gpio_irq_event_t event)
{
    CY_UNUSED_PARAMETER(event);
    // Increment global_count (passed as handler_arg) using a pointer
    uint32_t* count = (uint32_t*)handler_arg;
    *count = *count + 1;

    // Toggle pin P0_1 on every interrupt
    cyhal_gpio_toggle(P0_1);
}


void snippet_cyhal_gpio_interrupt()
{
    cy_rslt_t rslt;

    // Initialize pin P0_0 GPIO as an input pin
    rslt = cyhal_gpio_init(P0_0, CYHAL_GPIO_DIR_INPUT, CYHAL_GPIO_DRIVE_NONE, false);
    CY_ASSERT(CY_RSLT_SUCCESS == rslt);

    // Initialize pin P0_1 GPIO as an output with strong drive mode and initial value = true (high)
    rslt = cyhal_gpio_init(P0_1, CYHAL_GPIO_DIR_OUTPUT, CYHAL_GPIO_DRIVE_STRONG, true);
    CY_ASSERT(CY_RSLT_SUCCESS == rslt);

    // Register callback function - gpio_interrupt_handler and pass the value global_count
    cyhal_gpio_register_callback(P0_0, gpio_interrupt_handler, (void*)&global_count);

    // Enable falling edge interrupt event with interrupt priority set to 3
    cyhal_gpio_enable_event(P0_0, CYHAL_GPIO_IRQ_FALL, 3, true);
}

Defines

CYHAL_NC_PIN_VALUE

Integer representation of no connect pin (required to exist in all BSPs)

Typedefs

typedef void (*cyhal_gpio_event_callback_t)(void *callback_arg, cyhal_gpio_event_t event)

GPIO callback function type.

Enums

enum cyhal_gpio_event_t

cyhal_gpio_event_t: Pin events.

Values:

enumerator CYHAL_GPIO_IRQ_NONE

No interrupt.

enumerator CYHAL_GPIO_IRQ_RISE

Interrupt on rising edge.

enumerator CYHAL_GPIO_IRQ_FALL

Interrupt on falling edge.

enumerator CYHAL_GPIO_IRQ_BOTH

Interrupt on both rising and falling edges.

enum cyhal_gpio_direction_t

cyhal_gpio_direction_t: Pin direction.

Values:

enumerator CYHAL_GPIO_DIR_INPUT

Input pin.

enumerator CYHAL_GPIO_DIR_OUTPUT

Output pin.

enumerator CYHAL_GPIO_DIR_BIDIRECTIONAL

Input and output pin.

enum cyhal_gpio_drive_mode_t

cyhal_gpio_drive_mode_t: Pin drive mode.

note

When the drive_mode of the pin is set to CYHAL_GPIO_DRIVE_PULL_NONE , it is set to CYHAL_GPIO_DRIVE_STRONG if the direction of the pin is CYHAL_GPIO_DIR_OUTPUT or CYHAL_GPIO_DIR_BIDIRECTIONAL. If not, the drive_mode of the pin is set to CYHAL_GPIO_DRIVE_NONE.

Values:

enumerator CYHAL_GPIO_DRIVE_NONE

Digital Hi-Z.

Input only. Input init value(s): 0 or 1

enumerator CYHAL_GPIO_DRIVE_ANALOG

Analog Hi-Z.

Use only for analog purpose

enumerator CYHAL_GPIO_DRIVE_PULLUP

Pull-up resistor.

Input and output. Input init value(s): 1, output value(s): 0

enumerator CYHAL_GPIO_DRIVE_PULLDOWN

Pull-down resistor.

Input and output. Input init value(s): 0, output value(s): 1

enumerator CYHAL_GPIO_DRIVE_OPENDRAINDRIVESLOW

Open-drain, Drives Low.

Input and output. Input init value(s): 1, output value(s): 0

enumerator CYHAL_GPIO_DRIVE_OPENDRAINDRIVESHIGH

Open-drain, Drives High.

Input and output. Input init value(s): 0, output value(s): 1

enumerator CYHAL_GPIO_DRIVE_STRONG

Strong output.

Output only. Output init value(s): 0 or 1

enumerator CYHAL_GPIO_DRIVE_PULLUPDOWN

Pull-up and pull-down resistors.

Input and output. Input init value(s): 0 or 1, output value(s): 0 or 1

enumerator CYHAL_GPIO_DRIVE_PULL_NONE

No Pull-up or pull-down resistors.

Input and output. Input init value(s): 0 or 1, output value(s): 0 or 1

Functions

cy_rslt_t cyhal_gpio_init(cyhal_gpio_t pin, cyhal_gpio_direction_t direction, cyhal_gpio_drive_mode_t drive_mode, bool init_val)

Initialize the GPIO pin

See

Snippet 1: Reading value from GPIO.

Guidance for using gpio drive modes (

cyhal_gpio_drive_mode_t for details). For default use drive modes: Input GPIO direction - CYHAL_GPIO_DRIVE_NONE Output GPIO direction - CYHAL_GPIO_DRIVE_STRONG Bidirectional GPIO - CYHAL_GPIO_DRIVE_PULLUPDOWN

warning

Don't use CYHAL_GPIO_DRIVE_STRONG for input GPIO direction. It may cause an overcurrent issue.

Return

The status of the init request

Parameters
  • [in] pin: The GPIO pin to initialize

  • [in] direction: The pin direction

  • [in] drive_mode: The pin drive mode

  • [in] init_val: Initial value on the pin

void cyhal_gpio_free(cyhal_gpio_t pin)

Uninitialize the gpio peripheral and the cyhal_gpio_t object.

Parameters
  • [in] pin: Pin number

cy_rslt_t cyhal_gpio_configure(cyhal_gpio_t pin, cyhal_gpio_direction_t direction, cyhal_gpio_drive_mode_t drive_mode)

Configure the GPIO pin

See

Snippet 3: Reconfiguring a GPIO.

Return

The status of the configure request

Parameters
  • [in] pin: The GPIO pin

  • [in] direction: The pin direction

  • [in] drive_mode: The pin drive mode

void cyhal_gpio_write(cyhal_gpio_t pin, bool value)

Set the output value for the pin.

This only works for output & in_out pins.

See

Snippet 2: Writing value to a GPIO.

Parameters
  • [in] pin: The GPIO object

  • [in] value: The value to be set (high = true, low = false)

bool cyhal_gpio_read(cyhal_gpio_t pin)

Read the input value.

This only works for CYHAL_GPIO_DIR_INPUT & CYHAL_GPIO_DIR_BIDIRECTIONAL pins.

See

Snippet 1: Reading value from GPIO.

Return

The value of the IO (true = high, false = low)

Parameters
  • [in] pin: The GPIO object

void cyhal_gpio_toggle(cyhal_gpio_t pin)

Toggle the output value

See

Snippet 4: Interrupts on GPIO events.

Parameters
  • [in] pin: The GPIO object

void cyhal_gpio_register_callback(cyhal_gpio_t pin, cyhal_gpio_event_callback_t callback, void *callback_arg)

Register/clear a callback handler for pin events

This function will be called when one of the events enabled by cyhal_gpio_enable_event occurs.

See Snippet 4: Interrupts on GPIO events.

Parameters
  • [in] pin: The pin number

  • [in] callback: The function to call when the specified event happens. Pass NULL to unregister the handler.

  • [in] callback_arg: Generic argument that will be provided to the callback when called, can be NULL

void cyhal_gpio_enable_event(cyhal_gpio_t pin, cyhal_gpio_event_t event, uint8_t intr_priority, bool enable)

Enable or Disable the specified GPIO event

When an enabled event occurs, the function specified by cyhal_gpio_register_callback will be called.

See Snippet 4: Interrupts on GPIO events.

Parameters
  • [in] pin: The GPIO object

  • [in] event: The GPIO event

  • [in] intr_priority: The priority for NVIC interrupt events. Interrupt priorities specific to a pin may not be supported on all platforms. Refer to platform implementation specific documentation for details.

  • [in] enable: True to turn on interrupts, False to turn off

cy_rslt_t cyhal_gpio_connect_digital(cyhal_gpio_t pin, cyhal_source_t source, cyhal_signal_type_t type)

Connects a source signal and enables an input to a pin that, when triggered, will set the pins output.

Return

The status of the connection

Parameters
  • [in] pin: GPIO object

  • [in] source: Source signal obtained from another driver’s cyhal_<PERIPH>_enable_output

  • [in] type: Whether the incoming signal will act as a edge or level input

cy_rslt_t cyhal_gpio_enable_output(cyhal_gpio_t pin, cyhal_source_t *source)

Enables an output signal from a pin that is triggered by the pins input.

Return

The status of the output enable

Parameters
  • [in] pin: GPIO object

  • [out] source: Pointer to user-allocated source signal object which will be initialized by enable_output. source should be passed to (dis)connect_digital functions to (dis)connect the associated endpoints.

cy_rslt_t cyhal_gpio_disconnect_digital(cyhal_gpio_t pin, cyhal_source_t source)

Disconnects a source signal and disables an input to a pin.

Return

The status of the disconnection

Parameters
  • [in] pin: GPIO object

  • [in] source: Source signal from cyhal_<PERIPH>_enable_output to disable

cy_rslt_t cyhal_gpio_disable_output(cyhal_gpio_t pin)

Disables an output signal from a pin.

Return

The status of the output enable

Parameters
  • [in] pin: GPIO object