From ad2f5594bdab3d2f6d0d295fb5a547e935908a2c Mon Sep 17 00:00:00 2001 From: Grzegorz Ferenc Date: Wed, 15 Jan 2025 14:34:34 +0100 Subject: [PATCH] doc: hardware: Move LED example to a separate page Moved the steps for adding a LED node from VSC extension docs to a new page under Configuring devicetree. VSC-2802. Signed-off-by: Grzegorz Ferenc --- .../hardware/add_new_driver.rst | 6 +- .../hardware/add_new_led_example.rst | 98 +++++++++++++++++++ .../config_and_build/hardware/index.rst | 1 + .../releases/release-notes-changelog.rst | 2 + doc/nrf/shortcuts.txt | 4 + 5 files changed, 107 insertions(+), 4 deletions(-) create mode 100644 doc/nrf/app_dev/config_and_build/hardware/add_new_led_example.rst diff --git a/doc/nrf/app_dev/config_and_build/hardware/add_new_driver.rst b/doc/nrf/app_dev/config_and_build/hardware/add_new_driver.rst index 861b4910ed5d..72c5c5648ef9 100644 --- a/doc/nrf/app_dev/config_and_build/hardware/add_new_driver.rst +++ b/doc/nrf/app_dev/config_and_build/hardware/add_new_driver.rst @@ -20,16 +20,14 @@ In most of the cases you want to make it possible to configure some properties o For example, a sensor may need to allow configuring used GPIO pins or communication interface. A driver instance can be made configurable through a devicetree node that is compatible with a specific binding. -The devicetree bindings provide structure for the devicetree by declaring requirements for the content of devicetree nodes. -The :ref:`compatible ` property defines compatibility of a devicetree node with a devicetree binding. + +|devicetree_bindings| You can create a devicetree binding YAML file for your driver in the :file:`dts/bindings` directory of your project. If applicable, you can also use one of the existing DTS bindings available in the |NCS| or Zephyr. For implementation examples, see :file:`nrf/dts/bindings` and :file:`zephyr/dts/bindings` directories. See also :ref:`zephyr:devicetree` documentation for more information about devicetree. -For more information about devicetree bindings, read the :ref:`documentation about them in Zephyr `. - .. rst-class:: numbered-step Create the driver files diff --git a/doc/nrf/app_dev/config_and_build/hardware/add_new_led_example.rst b/doc/nrf/app_dev/config_and_build/hardware/add_new_led_example.rst new file mode 100644 index 000000000000..769fa61ff0db --- /dev/null +++ b/doc/nrf/app_dev/config_and_build/hardware/add_new_led_example.rst @@ -0,0 +1,98 @@ +.. _add_new_led_example: + +Adding a dimmable LED node +########################## + +.. contents:: + :local: + :depth: 2 + +This example demonstrates how to add support for a dimmable LED node to your board in an overlay file. + +To implement this example, you can either edit the devicetree files manually or use the |nRFVSC| with its `Devicetree language support`_ and the `Devicetree Visual Editor `_ (recommended). + +For more advanced LED control, you can also use the :ref:`LEDs module ` of the :ref:`Common Application Framework (CAF) `, which provides additional features, such as LED effects and power management integration. + +Implementation overview +*********************** + +This example uses Zephyr's generic binding for PWM LED controllers named ``pwm-leds``. + +|devicetree_bindings| + +See also the following related documentation: + +* :ref:`zephyr:pwm_api` - Zephyr's PWM driver API documentation +* :ref:`zephyr:dt-guide` - Zephyr's devicetree user guide + +.. rst-class:: numbered-step + +Open or create the overlay file to edit +*************************************** + +Overlay files are a category of devicetree's :ref:`zephyr:devicetree-in-out-files`. +These files can override node property values in multiple ways. + +You can add them to your configuration :ref:`manually ` or by using the |nRFVSC| (see `How to create devicetree files`_). + +.. rst-class:: numbered-step + +Add the PWM LED controller node +******************************* + +Complete the following steps: + +1. Add the controller node ``pwmleds`` under the root node in devicetree. +#. Add the ``pwm-leds`` binding for the driver to pick up. +#. Add LEDs as child nodes on the ``pwmleds`` controller node, with ``pwms`` and ``label`` properties. +#. Make sure the ``pwms`` property of the ``phandle-array`` type points to a PWM instance. + The PWM instance takes the pin number as its only parameter. + +The following code example uses pins 6 and 7 on the GPIO port 0 (``&pwm0``): + +.. code-block:: C + + / { // Devicetree root + // ... + pwmleds { // Controller node + compatible = "pwm-leds"; // Compatible binding + led_pwm_1 { + pwms = <&pwm0 6>; // Pin assigned to GPIO port 0 for LED 1 + label = "PWM LED 1"; + }; + + led_pwm_2 { + pwms = <&pwm0 7>; // Pin assigned to GPIO port 0 for LED 2 + label = "PWM LED 2"; + }; + }; + }; + +.. rst-class:: numbered-step + +Configure the PWM node +********************** + +Enable the referenced PWM0 node by setting ``status`` to ``"okay"`` and configuring the node's channels. +Use the ``&pwm0`` node label reference on the root of the file: + +.. code-block:: C + + &pwm0 { + status = "okay"; // Status + ch0-pin = <6>; // Pin assignment for channel 0 + ch1-pin = <7>; // Pin assignment for channel 1 + }; + +.. rst-class:: numbered-step + +Enable the LED PWM driver +************************* + +Add the following line to your :file:`prj.conf` file: + +.. code-block:: none + + CONFIG_LED_PWM=y + +Once you have added the LED PWM driver, :ref:`build your application ` and :ref:`program it to your board `. diff --git a/doc/nrf/app_dev/config_and_build/hardware/index.rst b/doc/nrf/app_dev/config_and_build/hardware/index.rst index 1ccc235309bf..b6dc4b14f03d 100644 --- a/doc/nrf/app_dev/config_and_build/hardware/index.rst +++ b/doc/nrf/app_dev/config_and_build/hardware/index.rst @@ -28,5 +28,6 @@ In particular, :ref:`zephyr:set-devicetree-overlays` explains how the base devic :caption: Subpages: add_new_driver + add_new_led_example pin_control use_gpio_pin_directly diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst index 9843f7943693..31746a31f42b 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst +++ b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst @@ -687,6 +687,8 @@ Documentation * New page :ref:`thingy53_precompiled` under :ref:`ug_thingy53`. This page includes some of the information previously located on the standalone page for getting started with Nordic Thingy:53. + * New page :ref:`add_new_led_example` under :ref:`configuring_devicetree`. + This page includes information previously located in the |nRFVSC| documentation. * Updated the :ref:`create_application` page with the :ref:`creating_add_on_index` section. * Removed the standalone page for getting started with Nordic Thingy:53. diff --git a/doc/nrf/shortcuts.txt b/doc/nrf/shortcuts.txt index 10b45aa6b0bb..2a8bd9da8fd1 100644 --- a/doc/nrf/shortcuts.txt +++ b/doc/nrf/shortcuts.txt @@ -263,3 +263,7 @@ .. |filter_samples_by_board| replace:: If you want to list samples available for one or more specific boards, `use the nRF Connect for Visual Studio Code extension to filter them `_. .. |54H_engb_2_8| replace:: The nRF54H20 DK Engineering A and B (up to version 0.8.2) are no longer supported starting with |NCS| v2.9.0. + +.. |devicetree_bindings| replace:: The devicetree bindings provide the structure for the content of the devicetree nodes. + The :ref:`compatible ` property defines the compatibility of a devicetree node with a devicetree binding. + For more information, read the :ref:`documentation about devicetree bindings in Zephyr `.