Differences

This shows you the differences between two versions of the page.

--- en:edu:zmitac:s2:aih:lab:nrf52gpio [2023/11/22 11:07] – [Concept of the Device Tree] ktokarz
+++ en:edu:zmitac:s2:aih:lab:nrf52gpio [2025/11/14 10:59] (current) – [Tasks for the laboratory on GPIO] ktokarz
@@ Line 1: / Line 1: @@
 ====== Laboratory on GPIO use in Zephyr OS ======
 GPIOs in Nordic Semiconductor nRF52840 can be handled by software with polling, with interrupts or using direct hardware connection with PPI (Programmable Peripheral Interconnect). In the first part of the laboratory, we will handle GPIO events with the software.
-The first example named “blinky” ((https://github.com/zephyrproject-rtos/zephyr/blob/main/samples/basic/blinky/src/main.c)) is a simple program that blinks the onboard LED. It can be used to check if all settings are set properly, and if all hardware and software modules work. After compilation and uploading of the program one LED on the board (LED0) should blink. Using this example we can analyze the way of setting parameters and using the GPIO input ports in Zephyr RTOS.
+The first example named “blinky” ((https://github.com/zephyrproject-rtos/zephyr/blob/main/samples/basic/blinky/src/main.c)) is a simple program that blinks the onboard LED. It can be used to check if all settings are set properly, and if all hardware and software modules work. After compilation and uploading of the program one LED on the board (LED0) should blink. Using this example we can analyze the way of setting parameters and using the GPIO input ports in Zephyr RTOS. Blinky is accessible as the example in the PlatformIO set of examples for the Nordic nRF52 platform as "zephyr-blink".
 ===== Concept of the Device Tree =====
@@ Line 80: / Line 80: @@
   - flags
 </code>
-===== Use of the device defined in the device tree =====
+===== Blinky - how to use the LED =====
-To use the hardware device in the program first there is a need to check if this device is defined in the device tree, and if so, set its main parameters. We can use the blinky example
+To use the hardware device in the program first there is a need to check if this device is defined in the device tree, and if so, set its main parameters. At the beginning of the blinky example, there is the fragment that gets the identifier of the led0 device and checks if the board used is capable of controlling the LED. If so takes the parameters of the LED from the device tree.
+<code>
+/* The devicetree node identifier for the "led0" alias. */
+#define LED0_NODE DT_ALIAS(led0)
+#if DT_NODE_HAS_STATUS(LED0_NODE, okay)
+#define LED0	DT_GPIO_LABEL(LED0_NODE, gpios)
+#define PIN	DT_GPIO_PIN(LED0_NODE, gpios)
+#define FLAGS	DT_GPIO_FLAGS(LED0_NODE, gpios)
+#else
+/* A build error here means your board isn't set up to blink an LED. */
+#error "Unsupported board: led0 devicetree alias is not defined"
+#define LED0	""
+#define PIN	0
+#define FLAGS	0
+#endif
+</code>
+  * **DT_ALIAS** macro takes the identifier and converts it to c compatible string (special characters are replaced with underscore symbols and all characters are converted to lowercase).
+  * **DT_NODE_HAS_STATUS** checks if the status of the node is OK.
+If the status is OK the label, the number of the pin, and flags are set as defined in the device tree. If not, all these elements are cleared. This may look like the overhead, but it is useful while we work with different hardware boards to prevent the compilation of the software for incompatible boards.
+The initial part of the code creates the structure which holds the parameters of the device and binds it with the LED0 identifier. At the end, the device is configured according to parameters taken from the device tree.
+After the configuration, the program jumps into the infinite while loop to blink the LED every 1000 ms.
+<code>
+/* ... */
+/* 1000 msec = 1 sec */
+#define SLEEP_TIME_MS   1000
+/* ... */
+void main(void)
+{
+	const struct device *dev;
+	bool led_is_on = true;
+	int ret;
+	dev = device_get_binding(LED0);
+	if (dev == NULL) {
+		return;
+	}
+	ret = gpio_pin_configure(dev, PIN, GPIO_OUTPUT_ACTIVE | FLAGS);
+	if (ret < 0) {
+		return;
+	}
+	while (1) {
+		gpio_pin_set(dev, PIN, (int)led_is_on);
+		led_is_on = !led_is_on;
+		k_msleep(SLEEP_TIME_MS);
+	}
+}
+</code>
+===== Direct register use =====
+Using a device tree is universal but can be found somehow complex. To obtain the same results, certainly, with losing the portability of the program between different microcontrollers and hardware platforms, there is a possibility to write directly to registers of the microcontroller. We need to know what is the base address of the P0 port and offsets of the registers responsible for pin configuration and state. Also, the pin number where the LED is connected. The values are presented in the table 1.
+<table>
+<caption>"Values needed for the program with direst register use"</caption>
+^ base address ^ direction register ^ port register ^ pin number ^
+| 0x50000000 | 0x514 | 0x504 | 14 |
+</table>
+The program can look like this.
+<code>
+#include <kernel.h>
+#define SLEEP_TIME_MS	   1000
+#define P0_BASE_ADDR	   0x50000000
+#define GPIO_PORT_REG      0x504 //offset of the register for output state
+#define GPIO_DIRECTION_REG 0x514 //offset of the register for defining pin function
+#define PIN_NUMBER         14    //led1 on the nRF52840 DK board
+int main(void)
+{
+    volatile uint32_t *p0_dir_reg = (volatile uint32_t *) (P0_BASE_ADDR + GPIO_DIRECTION_REG);
+    *p0_dir_reg |= (1 << PIN_NUMBER);
+    volatile uint32_t *p0_port_reg = (volatile uint32_t *) (P0_BASE_ADDR + GPIO_PORT_REG);
+    while (1) {
+	*p0_port_reg |= (1 << PIN_NUMBER);
+	k_msleep(SLEEP_TIME_MS);
+	*p0_port_reg &= ~(1 << PIN_NUMBER);
+	k_msleep(SLEEP_TIME_MS);
+    }
+    return 0;
+}
+</code>
+Some explanation of the "volatile" qualifier present in the example could help to clear some doubts. In general compilation and run of the above example without "volatile" should work properly. The troubles could start if there is some other part of the code that modifies the same registers. Because of optimization compiler could not read the port state but set it only, which could result in unexpected modification of other outputs. In general volatile qualifier should be used whenever the value of the variable could change unexpectedly. In practice, only three types of variables could change:
+  * Shared global variable modified by an interrupt service routine, used also in the main program
+  * Shared global variable within a multi-threaded application used by more than one thread
+  * Memory-mapped peripheral registers
+In our example, we have that third situation.
+===== Button example =====
+A similar example named “button” [5] uses one of the onboard buttons to generate interrupts and, at the same time, to control the onboard LED. The button example is not a part of the distribution of the Zephyr package, but can be downloaded from GitHub: https://github.com/zephyrproject-rtos ((https://github.com/zephyrproject-rtos)). Because of this, some paths for including libraries should be adjusted after import (usually it is enough to delete the “zephyr/” from paths marked erroneous).
+The button is included in the program similar way as LED.
+<code>
+#define SW0_NODE DT_ALIAS(sw0)
+#if DT_NODE_HAS_STATUS(SW0_NODE, okay)
+#define SW0_GPIO_LABEL DT_GPIO_LABEL(SW0_NODE, gpios)
+#define SW0_GPIO_PIN DT_GPIO_PIN(SW0_NODE, gpios)
+#define SW0_GPIO_FLAGS (GPIO_INPUT | DT_GPIO_FLAGS(SW0_NODE, gpios))
+#endif
+</code>
+Configuration of the button is done with the gpio_pin_configure() function:
+<code>
+gpio_pin_configure(button, SW0_GPIO_PIN, SW0_GPIO_FLAGS);
+</code>
+The button is configured to signal the interrupt.
+<code>
+gpio_pin_interrupt_configure(button, SW0_GPIO_PIN, GPIO_INT_EDGE_TO_ACTIVE);
+</code>
+As the cause of the press or release the callback function is started. The definition of this function can be like in the following code:
+<code>
+static struct gpio_callback button_cb_data;
+void button_pressed(const struct device *dev, struct gpio_callback *cb, uint32_t pins)
+{
+ printk("Button pressed at %" PRIu32 "\n", k_cycle_get_32());
+}
+</code>
+The callback function must be initialised and configured in the main:
+<code>
+gpio_init_callback(&button_cb_data, button_pressed, BIT(SW0_GPIO_PIN));
+gpio_add_callback(button, &button_cb_data);
+</code>
+Note that to be able to observe the UART port there is a need to enable the serial port in the file prj.conf:
+<code>
+CONFIG_SERIAL=y
+</code>
+and set the speed of transmission in platformio.ini:
+<code>
+monitor_speed = 115200
+</code>
+===== Tasks for the laboratory on GPIO =====
+  - Import the Blinky (zephyr_blink) example in the VS Code, as shown in the introduction to PlatformIO document.
+  - Find a zephyr-button example. It's not importable as the project, so the simplest solution is to replace files main.c and prj.conf in the already imported project (e.g. Blinky). Files can be found in the folder <code>..\.platformio\packages\framework-zephyr\samples\basic\button\src</code> The Zephyr-button code is also attached to this instruction at the bottom.
+  - Merge two projects “blink”, and “button” together to obtain the program that blinks LED0 continuously, calls the callback function with the interrupt generated with Button0, and controls the state of LED1 with Button1.
+===== The code for the laboratory on GPIO =====
+==== The Zephyr-button code example ====
+<code c>
+/*
+ * Copyright (c) 2016 Open-RnD Sp. z o.o.
+ * Copyright (c) 2020 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#include <zephyr/kernel.h>
+#include <zephyr/device.h>
+#include <zephyr/drivers/gpio.h>
+#include <zephyr/sys/util.h>
+#include <zephyr/sys/printk.h>
+#include <inttypes.h>
+#define SLEEP_TIME_MS 1
+/*
+ * Get button configuration from the devicetree sw0 alias. This is mandatory.
+ */
+#define SW0_NODE DT_ALIAS(sw0)
+#if !DT_NODE_HAS_STATUS(SW0_NODE, okay)
+#error "Unsupported board: sw0 devicetree alias is not defined"
+#endif
+static const struct gpio_dt_spec button = GPIO_DT_SPEC_GET_OR(SW0_NODE, gpios,
+      {0});
+static struct gpio_callback button_cb_data;
+/*
+ * The led0 devicetree alias is optional. If present, we'll use it
+ * to turn on the LED whenever the button is pressed.
+ */
+static struct gpio_dt_spec led = GPIO_DT_SPEC_GET_OR(DT_ALIAS(led0), gpios,
+     {0});
+void button_pressed(const struct device *dev, struct gpio_callback *cb,
+    uint32_t pins)
+{
+printk("Button pressed at %" PRIu32 "\n", k_cycle_get_32());
+}
+int main(void)
+{
+int ret;
+if (!gpio_is_ready_dt(&button)) {
+printk("Error: button device %s is not ready\n",
+       button.port->name);
+return 0;
+}
+ret = gpio_pin_configure_dt(&button, GPIO_INPUT);
+if (ret != 0) {
+printk("Error %d: failed to configure %s pin %d\n",
+       ret, button.port->name, button.pin);
+return 0;
+}
+ret = gpio_pin_interrupt_configure_dt(&button,
+      GPIO_INT_EDGE_TO_ACTIVE);
+if (ret != 0) {
+printk("Error %d: failed to configure interrupt on %s pin %d\n",
+ret, button.port->name, button.pin);
+return 0;
+}
+gpio_init_callback(&button_cb_data, button_pressed, BIT(button.pin));
+gpio_add_callback(button.port, &button_cb_data);
+printk("Set up button at %s pin %d\n", button.port->name, button.pin);
+if (led.port && !gpio_is_ready_dt(&led)) {
+printk("Error %d: LED device %s is not ready; ignoring it\n",
+       ret, led.port->name);
+led.port = NULL;
+}
+if (led.port) {
+ret = gpio_pin_configure_dt(&led, GPIO_OUTPUT);
+if (ret != 0) {
+printk("Error %d: failed to configure LED device %s pin %d\n",
+       ret, led.port->name, led.pin);
+led.port = NULL;
+} else {
+printk("Set up LED at %s pin %d\n", led.port->name, led.pin);
+}
+}
+printk("Press the button\n");
+if (led.port) {
+while (1) {
+/* If we have an LED, match its state to the button's. */
+int val = gpio_pin_get_dt(&button);
+if (val >= 0) {
+gpio_pin_set_dt(&led, val);
+}
+k_msleep(SLEEP_TIME_MS);
+}
+}
+return 0;
+}
+</code>