samples: sensor: adding a sample application for the STM32 qdec driver

Sample application for the STM32 quadrature encoder driver

Signed-off-by: Valerio Setti <[email protected]>

Author: valeriosetti

samples/sensor/qdec/CMakeLists.txt

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(qdec_sensor)
+
+FILE(GLOB app_sources src/*.c)
+target_sources(app PRIVATE ${app_sources})

samples/sensor/qdec/README.rst

@@ -0,0 +1,71 @@
+.. _qdec_sensor:
+
+Quadrature Decoder Sensor
+#########################
+
+Overview
+********
+
+This sample reads the value of the counter which has been configured in
+quadrature decoder mode.
+
+It requires:
+* an external mechanical encoder
+* pin to be properly configured in the device tree
+
+Building and Running
+********************
+
+In order to run this sample you need to:
+
+* enable the quadrature decoder device in your board's DT file or board overlay
+* add a new alias property named ``qdec0`` and make it point to the decoder
+  device you just enabled
+
+For example, here's how the overlay file of an STM32F401 board looks like when
+using decoder from TIM3 through pins PA6 and PA7:
+
+.. code-block:: dts
+
+    / {
+        aliases {
+            qdec0 = &qdec;
+        };
+    };
+
+    &timers3 {
+        status = "okay";
+
+        qdec: qdec {
+            status = "okay";
+            pinctrl-0 = <&tim3_ch1_pa6 &tim3_ch2_pa7>;
+            pinctrl-names = "default";
+            st,input-polarity-inverted;
+            st,input-filter-level = <FDIV32_N8>;
+            st,counts-per-revolution = <16>;
+        };
+    };
+
+Sample Output
+=============
+
+Once the MCU is started it prints the counter value every second on the
+console
+
+.. code-block:: console
+
+    Quadrature decoder sensor test
+    Position = 0 degrees
+    Position = 15 degrees
+    Position = 30 degrees
+    ...
+
+
+Of course the read value changes once the user manually rotates the mechanical
+encoder.
+
+.. note::
+
+    The reported increment/decrement can be larger/smaller than the one shown
+    in the above example. This depends on the mechanical encoder being used and
+    ``st,counts-per-revolution`` value.

samples/sensor/qdec/boards/nucleo_f401re.overlay

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) 2022 STMicroelectronics
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Application overlay for creating quadrature decoder device instance
+ */
+
+/ {
+	aliases {
+		qdec0 = &qdec;
+	};
+};
+
+&timers3 {
+	status = "okay";
+
+	qdec: qdec {
+		status = "okay";
+		pinctrl-0 = <&tim3_ch1_pa6 &tim3_ch2_pa7>;
+		pinctrl-names = "default";
+		st,input-polarity-inverted;
+		st,input-filter-level = <FDIV32_N8>;
+		st,counts-per-revolution = <16>;
+	};
+};

samples/sensor/qdec/prj.conf

@@ -0,0 +1,2 @@
+CONFIG_SENSOR=y
+CONFIG_PRINTK=y

samples/sensor/qdec/sample.yaml

@@ -0,0 +1,16 @@
+sample:
+  description: Usage quadrature decoder sensor
+  name: qdec_sensor
+tests:
+  sample.sensor.qdec_sensor:
+    tags: sensors
+    platform_allow: nucleo_f401re
+    timeout: 5
+    harness: console
+    harness_config:
+      type: multi_line
+      ordered: true
+      regex:
+        - "Quadrature decoder sensor test"
+        - "Position = (.*) degrees"
+      fixture: fixture_mech_encoder

samples/sensor/qdec/src/main.c

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2022 Valerio Setti <[email protected]>
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/kernel.h>
+#include <zephyr/device.h>
+#include <zephyr/drivers/sensor.h>
+#include <zephyr/sys/printk.h>
+
+void main(void)
+{
+	struct sensor_value val;
+	int rc;
+	const struct device *const dev = DEVICE_DT_GET(DT_ALIAS(qdec0));
+
+	if (!device_is_ready(dev)) {
+		printk("Qdec device is not ready\n");
+		return;
+	}
+
+	printk("Quadrature decoder sensor test\n");
+
+	while (true) {
+		rc = sensor_sample_fetch(dev);
+		if (rc != 0) {
+			printk("Failed to fetch sample (%d)\n", rc);
+			return;
+		}
+
+		rc = sensor_channel_get(dev, SENSOR_CHAN_ROTATION, &val);
+		if (rc != 0) {
+			printk("Failed to get data (%d)\n", rc);
+			return;
+		}
+
+		printk("Position = %d degrees", val.val1);
+
+		k_msleep(1000);
+	}
+}