Use GPIOs in high-level applications

Article
08/08/2023

Azure Sphere supports GPIOs (general-purpose input/output). A GPIO is a type of programmable digital pin on an integrated circuit. GPIOs don't have predefined functionality and their behavior can be customized by an application. Some common uses for GPIOs are to change the state of hardware devices, control LEDs, and read the state of switches.

Note

This topic describes how to use GPIOs in a high-level application. See Use peripherals in a real-time capable application for information about GPIO use in RTApps.

Azure Sphere high-level applications can communicate with GPIOs by calling Applibs GPIO APIs. The GPIO_HighLevelApp sample demonstrates how to communicate with GPIOs on an MT3620 device.

The following operations are supported for GPIO:

Read input
Set output to high or low
Polling / software interrupts

GPIO requirements

Applications that communicate with GPIOs must include the appropriate header files for GPIO and add GPIO settings to the application manifest.

All applications must set their target hardware and include the corresponding hardware definition header file.

Header Files

 #include <applibs/gpio.h>
 #include "path-to-your-target-hardware.h"

Replace "path-to-your-target-hardware.h" with the path to the header file for your hardware.

Application manifest settings

The GPIO settings in the application manifest list the GPIOs that are accessed by the application. Only one application can use a GPIO at a time. To configure these settings, add the Gpio capability to the application manifest, and then add each GPIO to the capability. Azure Sphere application manifest has more details.

In your code, use the constants that are defined for your hardware to identify the GPIOs. The compiler will translate these values to raw values when you build the app.

For example, here's an excerpt from an application manifest for an application that targets an MT3620 reference development board (RDB) and acquires three of its GPIOs (1, 8, and 12):

"Gpio": [ "$MT3620_RDB_HEADER1_PIN6_GPIO", "$MT3620_RDB_LED1_RED", "$MT3620_RDB_BUTTON_A" ]

The following excerpt shows how to specify the same GPIOs in an application that targets the Avnet MT3620 Starter Kit:

"Gpio": [ "$AVNET_MT3620_SK_GPIO1", "$AVNET_MT3620_SK_USER_LED_RED", "$AVNET_MT3620_SK_USER_BUTTON_A" ]

Open a GPIO as input

If you need to read from a GPIO but not write to it, you can open it as an input. Call GPIO_OpenAsInput to open a GPIO and set it to input. This will retrieve a file descriptor for operations on the GPIO. You can read from a GPIO while it is set to input, but you can't write to it. If a GPIO is set to input, you must close it before you can set it to output.

Open a GPIO as output

If you need to write to a GPIO, you must open it as an output. Call GPIO_OpenAsOutput to open a GPIO and set it to output. This will retrieve a file descriptor for operations on the GPIO, set the output mode, and the initial value. When a GPIO is set to output, you can write to it and read from it. If a GPIO is set to output, you must close it before you can set it to input.

Poll a GPIO

When the GPIO is open, you can monitor it for events, such as a button press. To do so, you need to set up a timer to poll the GPIO. Hardware interrupts for GPIOs are not supported on Azure Sphere, so you need to use polling. The GPIO sample demonstrates how to poll a GPIO.

Read from a GPIO

To read from the GPIO, call GPIO_GetValue.

Write to a GPIO

To write to a GPIO, call GPIO_SetValue.

Set the drive strength of a GPIO

The drive strength of a GPIO pin refers to the amount of current used to drive it. Typically, this amount of current is set to a default value. However, some scenarios, such as brighter LEDs or increased power to sensors, require tuning the drive strength to certain GPIO pins.

To set the drive strength, first use the gpiopin_request structure to specify the drive strength configuration for one or more GPIO pins. Next, pass gpiopin_request and GPIO_SET_PIN_CONFIG_IOCTL in an IOCTL call.

The following code snippet demonstrates how to set the drive strength of two GPIO pins, which are specified in the lineoffsets array of the gpiopin_request structure.

//get chip file descriptor
int chipfd = __z_azsp_open("/dev/gpiochip0", O_CLOEXEC);

//set drive strength for the requested pins
struct gpiopin_request pinreq;
memset(&pinreq, 0, sizeof(pinreq));
pinreq.linecount = 2;
pinreq.lineoffsets[0] = SAMPLE_RGBLED_BLUE;
pinreq.lineoffsets[1] = SAMPLE_RGBLED_RED;
pinreq.config_type = PIN_CONFIG_DRIVE_STRENGTH;
pinreq.config_arg = 16;

result = ioctl(chipfd, GPIO_SET_PIN_CONFIG_IOCTL, &pinreq);
if (result < 0) {
    close(chipfd);
    return -1;
}

//do other work like setting pins as output
struct gpiohandle_request request;
memset(&request, 0, sizeof(request));
request.flags = GPIOHANDLE_REQUEST_OUTPUT;
request.lines = 2;
request.lineoffsets[0] = SAMPLE_RGBLED_BLUE;
request.lineoffsets[1] = SAMPLE_RGBLED_RED;
request.default_values[0] = 1;
request.default_values[1] = 1;

result = ioctl(chipfd, GPIO_GET_LINEHANDLE_IOCTL, &request);
if (result < 0) {
    close(chipfd);
    return -1;
}

Close a GPIO

To close the GPIO, call the POSIX function close().

MT3620 support

The supported GPIO features for the MT3620 chip are listed in MT3620 Support Status. The MT3620 development board user guide describes the pin layout and pin functions on the MT3620 RDB.

The HardwareDefinitions folder in the Microsoft Azure Sphere SDK installation directory contains definitions for common Azure Sphere development boards, modules, and chips. It contains header and JSON files that define the master interfaces for the MT3620, MT3620 RDB, along with other MT3620 hardware. The default location for the HardwareDefinitions folder is C:\Program Files (x86)\Microsoft Azure Sphere SDK\Hardware Definitions on Windows and /opt/azurespheresdk/HardwareDefinitions on Linux.