samples: drivers: gpio: custom DTS binding demo

This sample shows how to define a custom devicetree binding to use
GPIO pins for a specific purpose.

Signed-off-by: Martin Jäger <[email protected]>

Author: martinjaeger

samples/drivers/gpio/custom_dts_binding/CMakeLists.txt

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.13.1)
+
+find_package(Zephyr HINTS $ENV{ZEPHYR_BASE})
+project(gpio_custom_dts_binding)
+
+target_sources(app PRIVATE src/main.c)

samples/drivers/gpio/custom_dts_binding/README.rst

@@ -0,0 +1,62 @@
+.. _gpio-custom-dts-binding-sample:
+
+GPIO with custom Devicetree binding
+###################################
+
+Overview
+********
+
+In Zephyr, all hardware-specific configuration is described in the devicetree.
+
+Consequently, also GPIO pins are configured in the devicetree and assigned to
+a specific purpose using a compatible.
+
+This is in contrast to other embedded environments like Arduino, where e.g.
+the direction (input / output) of a GPIO pin is configured in the application
+firmware.
+
+For typical use cases like LEDs or buttons, the existing ``gpio-leds`` or
+``gpio-keys`` compatibles can be used.
+
+This sample demonstrates how to use a GPIO pin for other purposes with a
+custom dts binding.
+
+We assume that a load with high current demands should be switched on or off
+via a MOSFET. The custom DTS binding for the power output controlled via a
+GPIO pin is specified in the file ``dts/bindings/power-output.yaml``. The gate
+driver for the MOSFET would be connected to the pin as specified in the
+``.overlay`` file in the boards folder.
+
+Building and Running
+********************
+
+For each board that should be supported, a ``.overlay`` file has to be defined
+in the ``boards`` subfolder.
+
+Building and Running for ST Nucleo L073RZ
+=========================================
+The sample can be built and executed for the
+:ref:`nucleo_l073rz_board` as follows:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/drivers/gpio/custom_dts_binding
+   :board: nucleo_l073rz
+   :goals: build flash
+   :compact:
+
+For demonstration purposes, we use the GPIO pin of the built-in LED.
+
+To build for another board, change "nucleo_l073rz" above to that board's name.
+
+Sample output
+=============
+
+The GPIO pin should be switched to active level after one second.
+
+The following output is printed (pin number and port may differ):
+
+.. code-block:: console
+
+   Initializing pin 5 on port GPIOA with inactive level.
+   Waiting one second.
+   Setting pin to active level.

samples/drivers/gpio/custom_dts_binding/boards/nucleo_l073rz.overlay

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) 2020 Martin Jäger / Libre Solar
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/ {
+	load_switch: load_switch {
+		compatible = "power-output";
+                /* using built-in LED pin for demonstration */
+		gpios = <&gpioa 5 GPIO_ACTIVE_HIGH>;
+	};
+};

samples/drivers/gpio/custom_dts_binding/dts/bindings/power-output.yaml

@@ -0,0 +1,11 @@
+# Copyright (c) 2020 Martin Jäger / Libre Solar
+# SPDX-License-Identifier: Apache-2.0
+
+description: GPIO pin to switch a power output on or off
+
+compatible: "power-output"
+
+properties:
+  gpios:
+    type: phandle-array
+    required: true

samples/drivers/gpio/custom_dts_binding/prj.conf

@@ -0,0 +1 @@
+CONFIG_GPIO=y

samples/drivers/gpio/custom_dts_binding/sample.yaml

@@ -0,0 +1,14 @@
+sample:
+  name: GPIO driver sample with custom DTS binding
+tests:
+  sample.drivers.gpio.custom_dts_binding:
+    tags: GPIO
+    platform_whitelist: nucleo_l073rz
+    depends_on: gpio
+    harness: console
+    harness_config:
+      type: multi_line
+      regex:
+        - "Initializing pin ([0-9]*) on port (.*) with inactive level."
+        - "Waiting one second."
+        - "Setting pin to active level."

samples/drivers/gpio/custom_dts_binding/src/main.c

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2020 Libre Solar Technologies GmbH
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr.h>
+#include <sys/printk.h>
+#include <drivers/gpio.h>
+
+#define LOAD_SWITCH DT_NODELABEL(load_switch)
+
+#if DT_NODE_EXISTS(LOAD_SWITCH)
+#define LOAD_SWITCH_PORT	DT_GPIO_LABEL(LOAD_SWITCH, gpios)
+#define LOAD_SWITCH_PIN		DT_GPIO_PIN(LOAD_SWITCH, gpios)
+#define LOAD_SWITCH_FLAGS	DT_GPIO_FLAGS(LOAD_SWITCH, gpios)
+#else
+#error "Overlay for power output node not properly defined."
+#endif
+
+void main(void)
+{
+	struct device *switch_dev = device_get_binding(LOAD_SWITCH_PORT);
+
+	printk("Initializing pin %d on port %s with inactive level.\n",
+		LOAD_SWITCH_PIN, LOAD_SWITCH_PORT);
+
+	gpio_pin_configure(switch_dev, LOAD_SWITCH_PIN,
+		LOAD_SWITCH_FLAGS | GPIO_OUTPUT_INACTIVE);
+
+	printk("Waiting one second.\n");
+
+	k_sleep(K_MSEC(1000));
+
+	printk("Setting pin to active level.\n");
+
+	gpio_pin_set(switch_dev, LOAD_SWITCH_PIN, 1);
+}