GPIOTE handling library

nRF5 SDK v14.1.0
Note
This library is obsolete and should not be used in new designs. Instead, you should use GPIOTE driver .

The general purpose Input/Output is organized in the nRF5 Series chips as one port with up to 32 I/Os (dependent on package) enabling access and control of up to 32 pins through one port. In most applications, the state of a GPIO or a change in state of a GPIO may trigger an application to take action or transition to another state.

The GPIO Tasks and Events (GPIOTE) provides functionality for accessing GPIO pins using tasks and events. The GPIO Task & Events (GPIOTE) library referred to as the the 'app_gpiote' in the SDK, facilitates application(s) to register for notification of change in state of one or more pins.

Since an application can consist of multiple independent modules, GPIOTE library allows several components to share the GPIOTE interrupt,each user defining a set of pins able to generate events to the user. When a GPIOTE interrupt occurs, the GPIOTE interrupt handler will identify pin transition(S) and notify each client registered for the transition.

Note
Components that register with the library are henceforth referred to as clients or users.
This library uses GPIOTE driver , which must be enabled and properly configured in sdk_config.h. You must specify GPIOTE_CONFIG_NUM_OF_LOW_POWER_EVENTS, which is the number of pins used for low power EVENTS_PORT including the pins used by this library.
Page-1 s.6 s.5 User 1 Registered for all pins for high→low and low→high User 1Registered for all pins for high→low and low→high s.1 User 2 Registered for all pins for high→low only User 2Registered for all pins for high→low only s.4 User 3 Registered for all pins for low→high only User 3Registered for all pins for low→high only Annotation/Comment Sheet.250 Sheet.251 Sheet.252 Sheet.253 Sheet.254 Sheet.255 Sheet.256 Sheet.257 Sheet.258 Sheet.259 Sheet.260 Sheet.261 Sheet.262 Sheet.263 This user is not registered for low→high and will not receive... This user is not registered for low→high and will not receive a notification through the registered callback for this event. Flowline1 Pin 1 transitions from low→high Pin 1 transitions from low→high Flowline1.265 User notified through registered callback User notified through registered callback Flowline1.266 User notified through registered callback User notified through registered callback Sheet.271 APP GPIOTE APP GPIOTE
Figure 1: Users are being notified of a pin transition event.

The GPIOTE users are responsible for configuring all their corresponding pins, except the SENSE field, which should be initialized to GPIO_PIN_CNF_SENSE_Disabled.

The module specifies on which pins events should be generated if the pin(s) goes from low->high or high->low or both directions.

Note
Even if the application is using the Scheduler , the GPIOTE event handlers will be called directly from the GPIOTE interrupt handler.

Initializing GPIOTE module

The initialization procedure must be performed before using any of the other APIs of the module. It is recommended to use initialization macro APP_GPIOTE_INIT instead of the routine app_gpiote_init as the former takes care of reserving needed memory for the each user requested in the MAX_USERS parameter of the macro. This parameter indicates how may users are going to be registering with the library.

// Macro to initialize GPIOTE module and reserving necessary memory for each of user.
APP_GPIOTE_INIT (MAX_USERS);
Note
Module initialization should be performed only once. Specifically when using the macro to avoid reserving memory for each module several times.

Registering with GPIOTE

Each user must register itself with the module to be notified of change in state of GPIO. During registry, the user must provide callback handler to notify of a transition event and pin transitions its is interested in. 32-bit bitmask is used to represent 32 GPIO pins as shown in Figure 2 below. User can register for transition from high to low and/or low to high.

Page-1 s.6 3 3 s.288 2 2 s.289 1 1 s.290 0 0 s.291 ... ... s.292 31 31 Sheet.293 MSB MSB Sheet.296 LSB LSB Sheet.298 32-bit bitmask 32-bit bitmask Sheet.299 GPIO31 GPIO31 Sheet.301 GPIO3 GPIO3 Sheet.325 GPIO2 GPIO2 Sheet.326 GPIO1 GPIO1 Sheet.327 GPIO0 GPIO0
Figure 2: GPIO Pin representation using 32-bit bitmask.

On successful registration, the user is assigned a user id and the user is expected to remember this identifier for all subsequent requests made to the module. This identifier is provided in the out parameter p_user_id . A sample registration is shown below.

// GPIOTE user identifier for the example module.
static app_gpiote_user_id_t m_example_user_id;
// GPIOTE event handler.
static void example_gpiote_event_handler(uint32_t event_pins_low_to_high, uint32_t event_pins_high_to_low);
.
.
.
uint32_t low_to_high_bitmask = 0x0000000F; // Bitmask to be notified of transition from low to high for GPIO 0-3
uint32_t high_to_low_bitmask = 0x0000000E; // Bitmask to be notified of transition from high to low for GPIO 0-2
uint32_t retval;
retval = app_gpiote_user_register (&m_example_user_id,
low_to_high_bitmask,
high_to_low_bitmask,
example_gpiote_event_handler);
if (retval != NRF_SUCCESS)
{
// Failed to register with user with GPIO module!
}
.
.
.
Note
It is possible for more than one user to register for same set/subset of GPIO pins; each of the concerned users will be notified of pin transition events.

By default, the GPIOTE is disabled on initialization. Therefore the GPIOTE has to be enabled by one of the users to start receiving GPIOTE state events. app_gpiote_user_enable is used to enable GPIOTE.

The following is a sample of registered user callback handling pin transition events.

// GPIOTE event handler.
void example_gpiote_event_handler (uint32_t event_pins_low_to_high, uint32_t event_pins_high_to_low)
{
.
.
.
if (event_pins_low_to_high & 0x00000001)
{
// GPIO pin 0 transitioned from low to high.
// Take necessary action.
}
if (event_pins_high_to_low & 0x00000004)
{
// GPIO pin 2 transitioned from high to low.
// Take necessary action.
}
.
.
.
}

Enable/Disable GPIOTE

The GPIOTE module can be enabled or disabled by a registered user at any point of time. No state transition events are received when the GPIOTE is disabled. On initialization, by default, the GPIOTE is disabled.

The following code snippet disables and enables the GPIOTE.

uint32_t retval;
// Enable notifications for example user module which is already registered.
retval = app_gpiote_user_disable (m_example_user_id);
if (retval != NRF_SUCCESS)
{
// Enabling notifications failed. Take corrective/needed action.
.
.
}
.
.
.
// Enable notifications for example user module which is already registered.
retval = app_gpiote_user_enable (m_example_user_id);
if (retval != NRF_SUCCESS)
{
// Enabling notifications failed. Take corrective/needed action.
.
.
}

Reading GPIOTE State

A registered user can read the current state of GPIOs by reading the state information. The following code snippets demonstrates a module reading the state information.

uint32_t retval;
uint32_t gpio_pin_state;
retval = app_gpiote_pins_state_get (m_example_user_id,&gpio_pin_state);
if (retval != NRF_SUCCESS)
{
// Failed to read state information. Take corrective action.
}
else
{
.
.
if (gpio_pins_state & 0x00000006) // Checks if pin one and two are set
{
// Take necessary action
}
.
.
}