diff --git a/applications/nrf_desktop/doc/bas.rst b/applications/nrf_desktop/doc/bas.rst index f175b8d10b01..084264ea79d2 100644 --- a/applications/nrf_desktop/doc/bas.rst +++ b/applications/nrf_desktop/doc/bas.rst @@ -22,7 +22,7 @@ Module events Configuration ************* -The module is enabled with the :ref:`CONFIG_DESKTOP_BAS_ENABLE ` option, that is implied by the :ref:`CONFIG_DESKTOP_BT_PERIPHERAL ` option. +To enable this module, use the :ref:`CONFIG_DESKTOP_BAS_ENABLE ` Kconfig option, that is implied by the :ref:`CONFIG_DESKTOP_BT_PERIPHERAL ` option. The Battery Service is required for the HID peripheral device. For more information about the Bluetooth® configuration in the nRF Desktop, see the :ref:`nrf_desktop_bluetooth_guide` documentation. diff --git a/applications/nrf_desktop/doc/ble_bond.rst b/applications/nrf_desktop/doc/ble_bond.rst index e02a3688a4ca..3a7bde6e2698 100644 --- a/applications/nrf_desktop/doc/ble_bond.rst +++ b/applications/nrf_desktop/doc/ble_bond.rst @@ -67,7 +67,7 @@ For example, the transition from :c:enumerator:`STATE_ERASE_PEER` to :c:enumerat When the transition occurs: -a. The :c:struct:`ble_peer_operation_event` with the defined :c:member:`ble_peer_operation_event.op` is submitted. +1. The :c:struct:`ble_peer_operation_event` with the defined :c:member:`ble_peer_operation_event.op` is submitted. For example, when the user confirms the erase advertising, the :c:struct:`ble_peer_operation_event` is submitted with :c:member:`ble_peer_operation_event.op` set to :c:enumerator:`PEER_OPERATION_ERASE_ADV`. #. The currently selected application local identity is updated (if anything changed). diff --git a/applications/nrf_desktop/doc/ble_discovery.rst b/applications/nrf_desktop/doc/ble_discovery.rst index 4f0ffff0cc7c..4cbb3cc4c546 100644 --- a/applications/nrf_desktop/doc/ble_discovery.rst +++ b/applications/nrf_desktop/doc/ble_discovery.rst @@ -31,7 +31,9 @@ Complete the following steps to configure the module: These modules are required for HID dongle that forwards the data from HID peripherals connected over Bluetooth. #. Make sure that the :kconfig:option:`CONFIG_BT_GATT_CLIENT` Kconfig option is enabled to support the GATT Client role. The GATT Client role is enabled by default by the :ref:`CONFIG_DESKTOP_BT_CENTRAL ` Kconfig option. -#. The |ble_discovery| module uses the :ref:`gatt_dm_readme` and selects the :kconfig:option:`CONFIG_BT_GATT_DM` Kconfig option to enable the library. + + The |ble_discovery| module uses the :ref:`gatt_dm_readme` and selects the :kconfig:option:`CONFIG_BT_GATT_DM` Kconfig option to enable the library. + #. Define the module configuration in the :file:`ble_discovery_def.h` file, located in the board-specific directory in the application configuration directory. You must define the following parameters for every nRF Desktop peripheral that connects with the given nRF Desktop central: diff --git a/applications/nrf_desktop/doc/ble_latency.rst b/applications/nrf_desktop/doc/ble_latency.rst index 125ea0564713..68234a2714dd 100644 --- a/applications/nrf_desktop/doc/ble_latency.rst +++ b/applications/nrf_desktop/doc/ble_latency.rst @@ -59,10 +59,10 @@ The module listens for the following events related to data transfer initiated b When these events are received, the module sets the connection latency to low. When the :ref:`nrf_desktop_config_channel` is no longer in use, and neither :ref:`nrf_desktop_ble_smp` nor :ref:`nrf_desktop_dfu_mcumgr` receive firmware updates (no mentioned events for ``LOW_LATENCY_CHECK_PERIOD_MS``), the module sets the connection latency to :kconfig:option:`CONFIG_BT_PERIPHERAL_PREF_LATENCY` to reduce the power consumption. - .. note:: - If the option :ref:`CONFIG_DESKTOP_BLE_LOW_LATENCY_LOCK ` is enabled, the LLPM connection latency is not increased unless the device is in the low power mode. +.. note:: + If the :ref:`CONFIG_DESKTOP_BLE_LOW_LATENCY_LOCK ` Kconfig option is enabled, the LLPM connection latency is not increased unless the device is in the low power mode. - When the device is in the low power mode and the events related to data transfer are not received, the connection latency is set to higher value to reduce the power consumption. + When the device is in the low power mode and the events related to data transfer are not received, the connection latency is set to higher value to reduce the power consumption. The ``ble_latency`` module receives :ref:`nrf_desktop_config_channel` events, but it is not configurable with the :ref:`nrf_desktop_config_channel`. The module does not register itself using the ``GEN_CONFIG_EVENT_HANDLERS`` macro. diff --git a/applications/nrf_desktop/doc/ble_passkey.rst b/applications/nrf_desktop/doc/ble_passkey.rst index c644ca880e00..72bd05d1cd7c 100644 --- a/applications/nrf_desktop/doc/ble_passkey.rst +++ b/applications/nrf_desktop/doc/ble_passkey.rst @@ -7,7 +7,7 @@ Bluetooth LE passkey module :local: :depth: 2 -Use the Bluetooth LE passkey module to enable pairing based on passkey for increased security. +Use the Bluetooth® LE passkey module to enable pairing based on passkey for increased security. Module events ************* @@ -22,7 +22,7 @@ Module events Configuration ************* -The module requires the basic Bluetooth® configuration, as described in :ref:`nrf_desktop_bluetooth_guide`. +The module requires the basic Bluetooth configuration, as described in :ref:`nrf_desktop_bluetooth_guide`. The module can be used only for nRF Desktop Bluetooth Peripheral devices (:ref:`CONFIG_DESKTOP_BT_PERIPHERAL `). Use the option :ref:`CONFIG_DESKTOP_BLE_ENABLE_PASSKEY ` to enable the module. @@ -42,5 +42,5 @@ The passkey input is handled in the :ref:`nrf_desktop_passkey`. .. note:: By default, Zephyr's Bluetooth Peripheral demands the security level 3 in case the passkey authentication is enabled. - If the nRF Desktop dongle is unable to achieve the security level 3, it will be unable to connect with the peripheral. + If the nRF Desktop dongle cannot achieve the security level 3, it cannot connect with the peripheral. The :kconfig:option:`CONFIG_BT_SMP_ENFORCE_MITM` option is disabled by default to allow the dongle to connect without the authentication. diff --git a/applications/nrf_desktop/doc/ble_qos.rst b/applications/nrf_desktop/doc/ble_qos.rst index 65b61a5cbf77..20892cf35521 100644 --- a/applications/nrf_desktop/doc/ble_qos.rst +++ b/applications/nrf_desktop/doc/ble_qos.rst @@ -27,15 +27,16 @@ Configuration The module requires the basic Bluetooth configuration, as described in :ref:`nrf_desktop_bluetooth_guide`. The QoS module uses the ``chmap_filter`` library, whose API is described in :file:`src/util/chmap_filter/include/chmap_filter.h`. -The library is linked if :ref:`CONFIG_DESKTOP_BLE_QOS_ENABLE ` Kconfig option is enabled. +The library is linked if the :ref:`CONFIG_DESKTOP_BLE_QOS_ENABLE ` Kconfig option is enabled. Enable the module using the :ref:`CONFIG_DESKTOP_BLE_QOS_ENABLE ` Kconfig option. The option selects :kconfig:option:`CONFIG_BT_HCI_VS_EVT_USER`, because the module uses vendor-specific HCI events. -You can use the :ref:`CONFIG_DESKTOP_BLE_QOS_STATS_PRINTOUT_ENABLE ` Kconfig option to enable real-time QoS information printouts through the USB CDC ACM port. -The :ref:`CONFIG_DESKTOP_USB_STACK_LEGACY ` Kconfig option must be enabled and the selected USB CDC ACM instance must be enabled, and specified in devicetree using ``ncs,ble-qos-uart`` DT chosen. +Use the :ref:`CONFIG_DESKTOP_BLE_QOS_STATS_PRINTOUT_ENABLE ` Kconfig option to enable real-time QoS information printouts through the USB CDC ACM port. +The :ref:`CONFIG_DESKTOP_USB_STACK_LEGACY ` Kconfig option must be enabled. +Also the selected USB CDC ACM instance must be enabled, and specified in devicetree using ``ncs,ble-qos-uart`` DT chosen. For an example of configuration that specifies the ``ncs,ble-qos-uart`` DT chosen, see the :file:`configuration/nrf52840dongle_nrf52840/app.overlay` file. -This option automatically selects other Kconfig options needed to handle stats printouts over the USB CDC ACM port: +This option automatically selects other Kconfig options needed to handle statistics printouts over the USB CDC ACM port: * :kconfig:option:`CONFIG_USB_COMPOSITE_DEVICE` * :kconfig:option:`CONFIG_USB_CDC_ACM` diff --git a/applications/nrf_desktop/doc/ble_scan.rst b/applications/nrf_desktop/doc/ble_scan.rst index fe66b3d712ea..0b511f00696f 100644 --- a/applications/nrf_desktop/doc/ble_scan.rst +++ b/applications/nrf_desktop/doc/ble_scan.rst @@ -42,7 +42,7 @@ Complete the following steps to enable the |ble_scan|: #. Make sure that the number of scan filters based on the Bluetooth name (:kconfig:option:`CONFIG_BT_SCAN_NAME_CNT`) is equal to the number of peripheral types the nRF Desktop central connects to. The |ble_scan| uses Bluetooth name filters to look for unbonded peripherals. The peripheral type may be either a mouse or a keyboard. -#. If you want to limit the number of attempts to connect to a device, you can use the connection attempt filter (:kconfig:option:`CONFIG_BT_SCAN_CONN_ATTEMPTS_FILTER`). +#. To limit the number of attempts to connect to a device, you can use the connection attempt filter (:kconfig:option:`CONFIG_BT_SCAN_CONN_ATTEMPTS_FILTER`). The Kconfig option is enabled by default. After the predefined number of disconnections or connection failures, the nRF Desktop central will no longer try to connect with the given peripheral device. This is done to prevent connecting and disconnecting with a peripheral in a never-ending loop. @@ -88,14 +88,14 @@ The following scanning scenarios are possible: Scanning module configuration ============================= -The |ble_scan| relies on :ref:`nrf_bt_scan_readme` to perform Bluetooth scanning. -The |ble_scan| selects :kconfig:option:`CONFIG_BT_SCAN` and :kconfig:option:`CONFIG_BT_SCAN_FILTER_ENABLE`. -Apart from that the following default values are applied: +The |ble_scan| relies on the :ref:`nrf_bt_scan_readme` library to perform Bluetooth scanning. +The module selects :kconfig:option:`CONFIG_BT_SCAN` and :kconfig:option:`CONFIG_BT_SCAN_FILTER_ENABLE`. +Apart from that, the following default values are applied: * :kconfig:option:`CONFIG_BT_SCAN_NAME_CNT` is set to ``2``. - By default, nRF Desktop dongle connects to peripherals that are either keyboard or mouse. + By default, the nRF Desktop dongle connects to peripherals that are either keyboard or mouse. * :kconfig:option:`CONFIG_BT_SCAN_ADDRESS_CNT` is set to :kconfig:option:`CONFIG_BT_MAX_PAIRED`. - The dongle scans for all of the bonded peripherals. + The dongle scans for all bonded peripherals. * :kconfig:option:`CONFIG_BT_SCAN_CONN_ATTEMPTS_FILTER` is enabled. .. _nrf_desktop_ble_scan_scanning_not_started: @@ -139,7 +139,8 @@ If the :ref:`CONFIG_DESKTOP_BLE_FORCED_SCAN_DURATION_S ` Kconfig option, the module switches to regular scanning. -The regular scanning can be interrupted by using connected peripherals and times out after the scan duration specified by :ref:`CONFIG_DESKTOP_BLE_SCAN_DURATION_S ` if there are peripherals connected over Bluetooth. +You can interrupt regular scanning by using connected peripherals. +The scanning times out after the duration specified by :ref:`CONFIG_DESKTOP_BLE_SCAN_DURATION_S ` if there are peripherals connected over Bluetooth. .. note:: The conditions described under :ref:`nrf_desktop_ble_scan_scanning_not_started` prevent the starting of the forced scan. diff --git a/applications/nrf_desktop/doc/buttons_sim.rst b/applications/nrf_desktop/doc/buttons_sim.rst index 12624361ee54..c7f7b3322acd 100644 --- a/applications/nrf_desktop/doc/buttons_sim.rst +++ b/applications/nrf_desktop/doc/buttons_sim.rst @@ -9,7 +9,7 @@ Button simulator module Use the |button_sim| to generate the sequence of simulated key presses. The time between subsequent key presses is defined as a module configuration option. -Generating keys can be started and stopped by pressing the predefined button. +To start or stop generating key presses, press the predefined button. Module events ************* @@ -34,7 +34,7 @@ To configure the |button_sim|: #. Define the interval between subsequent simulated button presses (:ref:`CONFIG_DESKTOP_BUTTONS_SIM_INTERVAL `). One second is used by default. -If you want the sequence to automatically restart after it ends, set :ref:`CONFIG_DESKTOP_BUTTONS_SIM_LOOP_FOREVER `. +If you want the sequence to automatically restart after it ends, set the :ref:`CONFIG_DESKTOP_BUTTONS_SIM_LOOP_FOREVER ` Kconfig option. By default, the sequence is generated only once. Implementation details @@ -43,4 +43,4 @@ Implementation details The |button_sim| generates button sequence using :c:struct:`k_work_delayable`, which resubmits itself. The work handler submits the press and the release of a single button from the sequence. -Receiving :c:struct:`button_event` with the key ID set to :ref:`CONFIG_DESKTOP_BUTTONS_SIM_TRIGGER_KEY_ID ` either stops generating the sequence (in case it is already being generated) or starts generating it. +Receiving :c:struct:`button_event` with the key ID set to :ref:`CONFIG_DESKTOP_BUTTONS_SIM_TRIGGER_KEY_ID ` either stops generating the sequence (if it is already being generated) or starts generating it. diff --git a/applications/nrf_desktop/doc/config_channel.rst b/applications/nrf_desktop/doc/config_channel.rst index 040bb82ef39b..d9a93dd4ef37 100644 --- a/applications/nrf_desktop/doc/config_channel.rst +++ b/applications/nrf_desktop/doc/config_channel.rst @@ -446,8 +446,8 @@ To register an application module as a configuration channel listener, complete .. note:: The module must be an early subscriber to make sure it will receive the event before the configuration channel transports (:ref:`nrf_desktop_usb_state` and :ref:`nrf_desktop_hids`). - Otherwise, the module may not receive the configuration channel requests at all. - In that case an error responses will be generated by configuration channel transport. + Otherwise, the module may not receive configuration channel requests at all. + In that case, an error response will be generated by the configuration channel transport. #. Call :c:macro:`GEN_CONFIG_EVENT_HANDLERS` in the :ref:`app_event_manager` event handler function registered by the application module: diff --git a/applications/nrf_desktop/doc/constlat.rst b/applications/nrf_desktop/doc/constlat.rst index 38f0729a414c..4a16f0de89ca 100644 --- a/applications/nrf_desktop/doc/constlat.rst +++ b/applications/nrf_desktop/doc/constlat.rst @@ -23,7 +23,7 @@ Module events Configuration ************* -Enable the module with the :ref:`CONFIG_DESKTOP_CONSTLAT_ENABLE ` option. +To enable the module, use the :ref:`CONFIG_DESKTOP_CONSTLAT_ENABLE ` Kconfig option. -You can set the :ref:`CONFIG_DESKTOP_CONSTLAT_DISABLE_ON_STANDBY ` to disable the constant latency interrupts when the device goes to the low power mode (on ``power_down_event``). -The constant latency interrupts are reenabled on ``wake_up_event``. +You can set the :ref:`CONFIG_DESKTOP_CONSTLAT_DISABLE_ON_STANDBY ` option to disable the constant latency interrupts when the device switches to the low power mode (on ``power_down_event``). +The constant latency interrupts are re-enabled on a ``wake_up_event``. diff --git a/applications/nrf_desktop/doc/cpu_meas.rst b/applications/nrf_desktop/doc/cpu_meas.rst index 51446a883094..c88b05b28bd8 100644 --- a/applications/nrf_desktop/doc/cpu_meas.rst +++ b/applications/nrf_desktop/doc/cpu_meas.rst @@ -22,15 +22,15 @@ Module events Configuration ************* -Enable the module using the :ref:`CONFIG_DESKTOP_CPU_MEAS_ENABLE ` option. -This Kconfig option selects the :kconfig:option:`CONFIG_CPU_LOAD` option. -The :kconfig:option:`CONFIG_CPU_LOAD` option enables :ref:`cpu_load`, that is used to perform the measurements. +To enable this module, use the :ref:`CONFIG_DESKTOP_CPU_MEAS_ENABLE ` Kconfig option. +This option selects the :kconfig:option:`CONFIG_CPU_LOAD` option. +The :kconfig:option:`CONFIG_CPU_LOAD` option enables :ref:`cpu_load` library that is used to perform the measurements. Set the time between subsequent CPU load measurements, in milliseconds, using the :ref:`CONFIG_DESKTOP_CPU_MEAS_PERIOD ` option. Implementation details ********************** -The module periodically submits the measured CPU load as :c:struct:`cpu_load_event` and resets the measurement. +The module periodically submits the measured CPU load as a :c:struct:`cpu_load_event` and resets the measurement. The event can be displayed in the logs or using the :ref:`nrf_profiler`. The :c:member:`cpu_load_event.load` presents the CPU load in 0.001% units. diff --git a/applications/nrf_desktop/doc/dev_descr.rst b/applications/nrf_desktop/doc/dev_descr.rst index c1da6cf816ae..6fee7fabd292 100644 --- a/applications/nrf_desktop/doc/dev_descr.rst +++ b/applications/nrf_desktop/doc/dev_descr.rst @@ -7,10 +7,10 @@ Device description module :local: :depth: 2 -The device description module defines custom GATT Service, which contains: +The device description module defines the custom GATT Service that contains: -* Information about whether the peripheral supports the Low Latency Packet Mode (LLPM) -* Hardware ID (HW ID) of the peripheral +* Information about whether the peripheral supports the Low Latency Packet Mode (LLPM). +* Hardware ID (HW ID) of the peripheral. To support the LLPM, the peripheral must use the SoftDevice Link Layer. This means that you must enable both the :kconfig:option:`CONFIG_BT_LL_SOFTDEVICE` and the :kconfig:option:`CONFIG_CAF_BLE_USE_LLPM` Kconfig options. @@ -20,13 +20,13 @@ The Service is mandatory for all nRF Desktop peripherals that connect to the nRF Module events ************* -The ``dev_descr`` module does not submit any event nor subscribe for any event. +The ``dev_descr`` module does not submit nor subscribe to any events. Configuration ************* -The module requires the basic Bluetooth configuration, as described in the :ref:`nrf_desktop_bluetooth_guide` documentation. -Make sure that both :ref:`CONFIG_DESKTOP_ROLE_HID_PERIPHERAL ` and :ref:`CONFIG_DESKTOP_BT_PERIPHERAL ` options are enabled. +The module requires the basic Bluetooth® configuration, as described in the :ref:`nrf_desktop_bluetooth_guide` documentation. +Make sure that both :ref:`CONFIG_DESKTOP_ROLE_HID_PERIPHERAL ` and :ref:`CONFIG_DESKTOP_BT_PERIPHERAL ` Kconfig options are enabled. The device description application module is enabled by the :ref:`CONFIG_DESKTOP_DEV_DESCR_ENABLE ` option, which is implied by :ref:`CONFIG_DESKTOP_BT_PERIPHERAL ` together with other features used by a Bluetooth LE HID peripheral device. The module selects the :ref:`CONFIG_DESKTOP_HWID ` option to make sure that the nRF Desktop Hardware ID utility is enabled. @@ -34,7 +34,7 @@ The utility uses Zephyr's :ref:`zephyr:hwinfo_api` to obtain the hardware ID and The :file:`dev_descr.h` file contains the UUIDs used by the custom GATT Service. The file is located in the :file:`configuration/common` directory. -The UUIDs must be the same for all devices to ensure that the central is able to read the provided information. +The UUIDs must be the same for all devices to ensure that the central can read the provided information. Implementation details ********************** diff --git a/applications/nrf_desktop/doc/dfu.rst b/applications/nrf_desktop/doc/dfu.rst index 9bd475d6ed0a..701b60a03587 100644 --- a/applications/nrf_desktop/doc/dfu.rst +++ b/applications/nrf_desktop/doc/dfu.rst @@ -20,12 +20,12 @@ Module events :end-before: table_dfu_end .. note:: - |nrf_desktop_module_event_note| + |nrf_desktop_module_event_note| Configuration ************* -The module can be used for the following devices: +You can use this module for the following devices: * nRF52, nRF53, and nRF54L Series - To perform the firmware upgrade, you must enable the bootloader. You can use the DFU module with either MCUboot or B0 bootloader. @@ -35,7 +35,7 @@ The module can be used for the following devices: The DFU module acts as a transport for the SUIT envelope used to update device firmware. For more information on how to enable the SUIT procedure, see the :ref:`nrf_desktop_suit` section. -Enable the DFU module using the :ref:`CONFIG_DESKTOP_CONFIG_CHANNEL_DFU_ENABLE ` option. +To enable the DFU module, use the :ref:`CONFIG_DESKTOP_CONFIG_CHANNEL_DFU_ENABLE ` Kconfig option. It requires the transport option :ref:`CONFIG_DESKTOP_CONFIG_CHANNEL_ENABLE ` to be selected, as it uses :ref:`nrf_desktop_config_channel` for the transmission of the update image. Set the value of :ref:`CONFIG_DESKTOP_CONFIG_CHANNEL_DFU_SYNC_BUFFER_SIZE ` to specify the size of the sync buffer (in words). @@ -61,7 +61,7 @@ If the MCUboot bootloader in the swap mode is selected, the DFU module does the If the MCUboot bootloader's direct-xip mode is used, the module does not mark the newly uploaded image as pending and does not confirm it after a successful boot. In that case, the DFU module assumes that the MCUboot direct-xip bootloader simply boots an image with the higher version, so there is no need to mark the image as pending and confirm it. -The :ref:`CONFIG_DESKTOP_CONFIG_CHANNEL_DFU_MCUBOOT_DIRECT_XIP ` option is used to inform the DFU module that the device uses the MCUboot bootloader in the direct-xip mode. +The :ref:`CONFIG_DESKTOP_CONFIG_CHANNEL_DFU_MCUBOOT_DIRECT_XIP ` Kconfig option is used to inform the DFU module that the device uses the MCUboot bootloader in the direct-xip mode. If the option is enabled, the DFU module reports the ``MCUBOOT+XIP`` bootloader name instead of ``MCUBOOT`` to indicate that the bootloader working in the direct-xip mode is used. The option depends on enabling the MCUboot bootloader (:kconfig:option:`CONFIG_BOOTLOADER_MCUBOOT`) and is enabled by default if the MCUboot direct-xip mode of operations is set (:kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_DIRECT_XIP`). See the :ref:`nrf_desktop_bootloader` section for more information on the MCUboot bootloader configuration. @@ -87,7 +87,7 @@ Non-volatile memory access synchronization with other DFU methods The DFU module leverages the :ref:`nrf_desktop_dfu_lock` to synchronize non-volatile memory access with other DFU methods (for example, SMP DFU). If multiple DFU transports are enabled in your application configuration, make sure that the following conditions are met: -* The :ref:`CONFIG_DESKTOP_DFU_LOCK ` option is enabled +* The :ref:`CONFIG_DESKTOP_DFU_LOCK ` Kconfig option is enabled * All of the used DFU transports use the :ref:`nrf_desktop_dfu_lock`. On each DFU attempt, the module attempts to claim ownership over the DFU non-volatile memory using the DFU Lock API. diff --git a/applications/nrf_desktop/doc/fast_pair_app.rst b/applications/nrf_desktop/doc/fast_pair_app.rst index 8a89e6c89db9..1f19cc0e65d6 100644 --- a/applications/nrf_desktop/doc/fast_pair_app.rst +++ b/applications/nrf_desktop/doc/fast_pair_app.rst @@ -10,7 +10,7 @@ Fast Pair module The Fast Pair module is used to: * Update the Fast Pair advertising payload to automatically switch between showing and hiding user interface (UI) pairing indication on the Fast Pair Seeker. - The UI indication must be displayed only if the Provider can bond with new peers on the currently used Bluetooth local identity. + The UI indication must be displayed only if the Provider can bond with new peers on the currently used Bluetooth® local identity. * Reject a normal Bluetooth pairing when outside of the pairing mode. * Remove the Fast Pair advertising payload for the dongle peer. @@ -44,7 +44,7 @@ The Fast Pair module is enabled using :ref:`CONFIG_DESKTOP_FAST_PAIR `) Kconfig option instead. - Setting the peripheral latency Bluetooth LE connection parameter to ``0`` for a connection that uses Low Latency Packet Mode connection interval on peripheral leads to keeping the high frequency clock enabled. - That mitigates the extra HID report latency caused by the high frequency clock startup delay. + The module is deprecated. + Use the :ref:`CONFIG_DESKTOP_BLE_LOW_LATENCY_LOCK `) Kconfig option instead. + Setting the peripheral latency Bluetooth LE connection parameter to ``0`` for a connection that uses Low Latency Packet Mode connection interval on peripheral leads to keeping the high frequency clock enabled. + That mitigates the extra HID report latency caused by the high frequency clock startup delay. Module events ************* @@ -30,15 +30,16 @@ Module events Configuration ************* -The module is not supported for nRF54H SoC Series (:kconfig:option:`CONFIG_SOC_SERIES_NRF54HX`). +To enable the module, use the :kconfig:option:`CONFIG_DESKTOP_HFCLK_LOCK_ENABLE` Kconfig option. -Make sure that Bluetooth LE Low Latency Packet Mode (LLPM) is enabled in configuration (:kconfig:option:`CONFIG_CAF_BLE_USE_LLPM`). -Using LLPM connection parameters reduces HID data latency far more significantly than enabling the module. +Make sure that you have enabled the Bluetooth LE Low Latency Packet Mode (LLPM) (:kconfig:option:`CONFIG_CAF_BLE_USE_LLPM`). +Using LLPM connection parameters reduces HID data latency more than enabling the module. -Enable the module with the :ref:`CONFIG_DESKTOP_HFCLK_LOCK_ENABLE ` Kconfig option. +.. note:: + The module is not supported for nRF54H Series SoC (:kconfig:option:`CONFIG_SOC_SERIES_NRF54HX`). Implementation details ********************** -The high frequency clock is disabled on :c:struct:`power_down_event` and reenabled on :c:struct:`wake_up_event`. +The high frequency clock is disabled on a :c:struct:`power_down_event` and re-enabled on a :c:struct:`wake_up_event`. This is done to reduce the power consumption. diff --git a/applications/nrf_desktop/doc/hid_forward.rst b/applications/nrf_desktop/doc/hid_forward.rst index 908631c9a262..d6b54ab04c60 100644 --- a/applications/nrf_desktop/doc/hid_forward.rst +++ b/applications/nrf_desktop/doc/hid_forward.rst @@ -56,11 +56,11 @@ Complete the following steps to configure the module: Those options affect :ref:`nrf_desktop_usb_state` that subscribes for HID boot reports. The Dongle forwards HID reports from both mouse and keyboard, and so either option works if you want to have the Dongle work as boot mouse or boot keyboard. - For more information about the configuration of the HID boot protocol, see the boot protocol configuration section in the :ref:`nrf_desktop_usb_state` documentation. + For more information about the configuration of the HID boot protocol, see the Boot protocol configuration section in the :ref:`nrf_desktop_usb_state` documentation. #. Make sure that the value of :ref:`CONFIG_DESKTOP_HID_FORWARD_SUBSCRIBER_COUNT ` Kconfig option matches number of USB HID class instances configured in :ref:`nrf_desktop_usb_state`. nRF Desktop dongle can use one or more instances of the USB HID class. By default, the module uses a dedicated HID subscriber (USB HID class instance) for every BLE bonded HID peripheral. - For more details about interactions with USB, see the `Interaction with the USB`_ section. + For more details, see the `Interaction with the USB`_ section. Implementation details ********************** diff --git a/applications/nrf_desktop/doc/hid_state.rst b/applications/nrf_desktop/doc/hid_state.rst index 1bc4efd32a40..4fb3ebe404e1 100644 --- a/applications/nrf_desktop/doc/hid_state.rst +++ b/applications/nrf_desktop/doc/hid_state.rst @@ -29,7 +29,7 @@ Module events Configuration ************* -The |hid_state| is enabled by the :ref:`CONFIG_DESKTOP_HID_STATE_ENABLE ` option which is implied by the :ref:`CONFIG_DESKTOP_ROLE_HID_PERIPHERAL ` option. +To enable the |hid_state|, use the :ref:`CONFIG_DESKTOP_HID_STATE_ENABLE ` Kconfig option that is implied by the :ref:`CONFIG_DESKTOP_ROLE_HID_PERIPHERAL ` option. An nRF Desktop peripheral uses the |hid_state| to generate HID reports based on the user input. For details related to HID configuration in the nRF Desktop, see the :ref:`nrf_desktop_hid_configuration` documentation. @@ -118,13 +118,13 @@ You must define all of the mentioned data in this configuration file, and specif Report expiration ================= -With the :ref:`CONFIG_DESKTOP_HID_REPORT_EXPIRATION ` configuration option, you can set the amount of time after which a key will be considered expired. +With the :ref:`CONFIG_DESKTOP_HID_REPORT_EXPIRATION ` Kconfig option, you can set the amount of time after which a key will be considered expired. The higher the value, the longer the period after which the nRF Desktop application will recall pressed keys when the connection is established. Queue event size ================ -With the :ref:`CONFIG_DESKTOP_HID_EVENT_QUEUE_SIZE ` configuration option, you can set the number of elements on the queue where the keys are stored before the connection is established. +With the :ref:`CONFIG_DESKTOP_HID_EVENT_QUEUE_SIZE ` Kconfig option, you can set the number of elements on the queue where the keys are stored before the connection is established. When a key state changes (it is pressed or released) before the connection is established, an element containing this key's usage is pushed onto the queue. If there is no space in the queue, the oldest element is released. @@ -208,7 +208,7 @@ This queue preserves an order at which input data events are received. Storing limitations ------------------- -The number of events that can be inserted into the queue is limited by :ref:`CONFIG_DESKTOP_HID_EVENT_QUEUE_SIZE ` option. +The number of events that can be inserted into the queue is limited by the :ref:`CONFIG_DESKTOP_HID_EVENT_QUEUE_SIZE ` Kconfig option. Discarding events When there is no space for a new input event, the |hid_state| tries to free space by discarding the oldest event in the queue. @@ -259,7 +259,7 @@ Depending on the connection method, this event can be submitted: The :c:struct:`report_state` structure serves the following purposes: * Tracks the state of the connection. -* Contains the link connecting the object to the right :c:struct:`report_data` structure, from which the data is taken when the HID report is formed. +* Contains the link connecting the object to the right :c:struct:`report_data` structure from which the data is taken when the HID report is formed. * Tracks the number of reports of the associated type that were sent to the subscriber. Forming HID reports @@ -270,7 +270,7 @@ The :c:struct:`report_data` structure is passed as an argument to this function. .. note:: The HID report formatting function must work according to the HID report descriptor (``hid_report_desc``). - The source file containing the descriptor is given by :ref:`CONFIG_DESKTOP_HID_REPORT_DESC ` option. + The source file containing the descriptor is provided by the :ref:`CONFIG_DESKTOP_HID_REPORT_DESC ` Kconfig option. Handling HID keyboard LED state =============================== diff --git a/applications/nrf_desktop/doc/hids.rst b/applications/nrf_desktop/doc/hids.rst index 6394cc4a9f95..bb409c0fea12 100644 --- a/applications/nrf_desktop/doc/hids.rst +++ b/applications/nrf_desktop/doc/hids.rst @@ -27,20 +27,22 @@ Configuration Complete the following steps to configure the module: 1. Complete the basic Bluetooth configuration, as described in :ref:`nrf_desktop_bluetooth_guide`. - Make sure that both :ref:`CONFIG_DESKTOP_ROLE_HID_PERIPHERAL ` and :ref:`CONFIG_DESKTOP_BT_PERIPHERAL ` options are enabled. + +#. Make sure that both :ref:`CONFIG_DESKTOP_ROLE_HID_PERIPHERAL ` and :ref:`CONFIG_DESKTOP_BT_PERIPHERAL ` Kconfig options are enabled. The HID Service application module is enabled by the :ref:`CONFIG_DESKTOP_HIDS_ENABLE ` option, which is implied by :ref:`CONFIG_DESKTOP_BT_PERIPHERAL ` together with other GATT Services that are required for a HID device. -#. The :ref:`CONFIG_DESKTOP_HIDS_ENABLE ` option selects the following Kconfig options: + + The :ref:`CONFIG_DESKTOP_HIDS_ENABLE ` option selects the following Kconfig options: * The :kconfig:option:`CONFIG_BT_HIDS` option that automatically enables the :ref:`hids_readme`. * The :kconfig:option:`CONFIG_BT_CONN_CTX` option that automatically enables the :ref:`bt_conn_ctx_readme`, which is required by the |GATT_HID|. -#. The nRF Desktop application modifies the defaults of Kconfig option values, defined by the :ref:`hids_readme`, to tailor the default configuration to application needs. - The configuration is tailored for either nRF Desktop mouse (:ref:`CONFIG_DESKTOP_PERIPHERAL_TYPE_MOUSE `) or nRF Desktop keyboard (:ref:`CONFIG_DESKTOP_PERIPHERAL_TYPE_KEYBOARD `). - For more details, see the :file:`src/modules/Kconfig.hids` file. +The nRF Desktop application modifies the default Kconfig option values, defined by the :ref:`hids_readme`, to tailor the default configuration to application needs. +The configuration is tailored for either nRF Desktop mouse (:ref:`CONFIG_DESKTOP_PERIPHERAL_TYPE_MOUSE `) or nRF Desktop keyboard (:ref:`CONFIG_DESKTOP_PERIPHERAL_TYPE_KEYBOARD `). +For more details, see the :file:`src/modules/Kconfig.hids` file. - .. tip:: - If the HID report configuration is identical to the default configuration of either nRF Desktop mouse or keyboard, you do not need to modify the |GATT_HID| configuration. - Otherwise, see :ref:`hids_readme` documentation for configuration details. +.. tip:: + If the HID report configuration is identical to the default configuration of either nRF Desktop mouse or keyboard, you do not need to modify the |GATT_HID| configuration. + Otherwise, see :ref:`hids_readme` documentation for configuration details. The HID Service application module forwards the information about the enabled HID notifications to other application modules using ``hid_report_subscription_event``. These notifications are enabled by the connected Bluetooth® Central. @@ -97,7 +99,7 @@ HID notifications ================= The ``hid_notification_event`` is used to synchronize the information about enabling or disabling the HID notifications for the HID input report. -The event is submitted when the |GATT_HID| calls a callback related to enabling or disabling the notifications and the event is received only by the ``hids`` application module. +The event is submitted when the |GATT_HID| calls a callback related to enabling or disabling the notifications and the event is received only by the ``hids`` (Question: where does this "hids" refer to?) application module. Transport for configuration channel =================================== diff --git a/applications/nrf_desktop/doc/info.rst b/applications/nrf_desktop/doc/info.rst index 558f024e756c..950951503549 100644 --- a/applications/nrf_desktop/doc/info.rst +++ b/applications/nrf_desktop/doc/info.rst @@ -28,10 +28,11 @@ Module events Configuration ************* -The module selects the :ref:`CONFIG_DESKTOP_HWID ` option to make sure that nRF Desktop Hardware ID utility is enabled. -The utility uses Zephyr's :ref:`zephyr:hwinfo_api` to obtain the hardware ID and selects the :kconfig:option:`CONFIG_HWINFO` Kconfig option to automatically enable the required driver. +To enable the module, use the :ref:`CONFIG_DESKTOP_CONFIG_CHANNEL_ENABLE ` Kconfig option. +The same option enables the :ref:`nrf_desktop_config_channel`. -The module is enabled with the same Kconfig option as the :ref:`nrf_desktop_config_channel`: :ref:`CONFIG_DESKTOP_CONFIG_CHANNEL_ENABLE `. +The module selects the :ref:`CONFIG_DESKTOP_HWID ` Kconfig option to make sure that nRF Desktop Hardware ID utility is enabled. +The utility uses Zephyr's :ref:`zephyr:hwinfo_api` to obtain the hardware ID and selects the :kconfig:option:`CONFIG_HWINFO` Kconfig option to automatically enable the required driver. Implementation details ********************** diff --git a/applications/nrf_desktop/doc/led_state.rst b/applications/nrf_desktop/doc/led_state.rst index 8ca0d454243c..e3c934ae8d5b 100644 --- a/applications/nrf_desktop/doc/led_state.rst +++ b/applications/nrf_desktop/doc/led_state.rst @@ -28,7 +28,7 @@ The module controls LEDs defined by enumerators in :c:enum:`led_id`: * :c:enumerator:`LED_PEER_STATE_CONNECTED` - Bluetooth peer is connected. * :c:enumerator:`LED_PEER_STATE_PEER_SEARCH` - Device is looking for a peer, either by scanning or advertising. * :c:enumerator:`LED_PEER_STATE_CONFIRM_SELECT` - Bluetooth peer is being selected (the device is waiting for confirmation). - * :c:enumerator:`LED_PEER_STATE_CONFIRM_ERASE` - Device is waiting for user confirmation to erase peers (for Bluetooth® Central) or start erase advertising (for Bluetooth® Peripheral). + * :c:enumerator:`LED_PEER_STATE_CONFIRM_ERASE` - Device is waiting for user confirmation to erase peers (for Bluetooth Central) or start erase advertising (for Bluetooth Peripheral). * :c:enumerator:`LED_PEER_STATE_ERASE_ADV` - Device is advertising for peer erase. For the complete description of peer management, see :ref:`nrf_desktop_ble_bond`. @@ -51,8 +51,8 @@ Module events Configuration ************* -The |led_state| is enabled when you set the :kconfig:option:`CONFIG_CAF_LEDS` option. -You must also configure :ref:`caf_leds`, which is used as a sink module for ``led_state``. +To enable the |led_state|, set the :kconfig:option:`CONFIG_CAF_LEDS` Kconfig option. +You must also configure the :ref:`caf_leds` that is used as a sink module for ``led_state``. For every board that has this option enabled, you must define the module configuration. The configuration must be defined in the file named :ref:`CONFIG_DESKTOP_LED_STATE_DEF_PATH ` located in the board-specific directory in the application configuration directory. @@ -60,8 +60,8 @@ By default, the file is named as :file:`led_state_def.h`. The configuration consists of the following elements: -* ``led_map`` - Maps the :c:enum:`led_id` values to IDs used by :ref:`caf_leds`. - If no physical LED is assigned to a :c:enum:`led_id` value, assign :c:macro:`LED_UNAVAILABLE` as the ID used by :ref:`caf_leds`. +* ``led_map`` - Maps the :c:enum:`led_id` values to IDs used by the :ref:`caf_leds`. + If no physical LED is assigned to a :c:enum:`led_id` value, assign :c:macro:`LED_UNAVAILABLE` as the ID used by the :ref:`caf_leds`. * ``led_system_state_effect`` - Defines the LED effects used to show the system states. The effect must be defined for every system state. * ``led_peer_state_effect`` - Defines the LED effects used to show the Bluetooth peer states. diff --git a/applications/nrf_desktop/doc/led_stream.rst b/applications/nrf_desktop/doc/led_stream.rst index 75b2c024e44f..997d19e806a8 100644 --- a/applications/nrf_desktop/doc/led_stream.rst +++ b/applications/nrf_desktop/doc/led_stream.rst @@ -24,7 +24,7 @@ Configuration ************* The module receives LED effects through the :ref:`nrf_desktop_config_channel` and displays them using the :ref:`caf_leds`. -For this reason, make sure that both :kconfig:option:`CONFIG_CAF_LEDS` and :ref:`CONFIG_DESKTOP_CONFIG_CHANNEL_ENABLE ` options are set. +For this reason, make sure that both :kconfig:option:`CONFIG_CAF_LEDS` and :ref:`CONFIG_DESKTOP_CONFIG_CHANNEL_ENABLE ` Kconfig options are set. To enable the module, use the :ref:`CONFIG_DESKTOP_LED_STREAM_ENABLE ` Kconfig option. @@ -57,7 +57,7 @@ Implementation details ********************** The module receives LED effects as ``config_event``. -The effects are sent to :ref:`caf_leds` as ``led_event``. +The effects are sent to the :ref:`caf_leds` as ``led_event``. Displaying the sequence begins when the first LED effect is received by the |led_stream|. Every received LED effect has a predefined duration. diff --git a/applications/nrf_desktop/doc/motion.rst b/applications/nrf_desktop/doc/motion.rst index c417d2ad2b5b..55ced17ab64e 100644 --- a/applications/nrf_desktop/doc/motion.rst +++ b/applications/nrf_desktop/doc/motion.rst @@ -91,7 +91,7 @@ The X and Y coordinates of subsequent vertexes of the octagon are defined as the You can configure the path with the following options: * :ref:`CONFIG_DESKTOP_MOTION_SIMULATED_EDGE_TIME ` - Sets how long each edge is traced. - To speed up calculations, this Kconfig option value must be set to a power of two. + To speed up calculations, set this Kconfig option value to a power of two. * :ref:`CONFIG_DESKTOP_MOTION_SIMULATED_SCALE_FACTOR ` - Scales the size of the octagon. The Kconfig option's value is used as the ``SCALE`` factor in the ``coords`` array. @@ -178,7 +178,7 @@ Upon connection, the following happens: #. Waits for the indication that the :c:struct:`motion_event` data was transmitted to the host. This is done when the module receives the :c:struct:`hid_report_sent_event` event. -#. At this point, a next motion sampling is performed and the next :c:struct:`motion_event` sent. +#. The next motion sampling is performed and the next :c:struct:`motion_event` sent. The module continues to sample data until disconnection or when there is no motion detected. The ``motion`` module assumes no motion when a number of consecutive samples equal to :ref:`CONFIG_DESKTOP_MOTION_SENSOR_EMPTY_SAMPLES_COUNT ` returns zero on both axis. @@ -227,6 +227,6 @@ You can perform the following actions to ensure that non-zero motion is reported * ``Simulated movement data`` Increase the value of the used scale factor or reduce time for transition between two points in the trajectory to increase the generated motion values. Keep in mind that the generated shape is periodically repeated, so the transition time between two points in the trajectory should not be too short. - If it is, it might cause the same point to generate twice which would also result in submitting a :c:struct:`motion_event` with values set to ``0`` for both axes. + If it is, it might cause the same point to generate twice, which would also result in submitting a :c:struct:`motion_event` with values set to ``0`` for both axes. See the :ref:`nrf_desktop_motion_configuration` section for details on how to modify configuration for a given implementation of the module. diff --git a/applications/nrf_desktop/doc/nrf_profiler_sync.rst b/applications/nrf_desktop/doc/nrf_profiler_sync.rst index 0e931d3461ff..2dfc8850311d 100644 --- a/applications/nrf_desktop/doc/nrf_profiler_sync.rst +++ b/applications/nrf_desktop/doc/nrf_profiler_sync.rst @@ -28,7 +28,7 @@ Configuration ************* A predefined signal on the GPIO is used to simultaneously generate synchronization nRF Profiler events on both devices. -For this reason, you must enable the :kconfig:option:`CONFIG_GPIO` option. +For this reason, you must enable the :kconfig:option:`CONFIG_GPIO` Kconfig option. You must also enable the :kconfig:option:`CONFIG_APP_EVENT_MANAGER_PROFILER_TRACER` Kconfig option. The nRF Profiler synchronization module generates an :ref:`nrf_profiler` event (:c:struct:`sync_event`) that is not an :ref:`app_event_manager` event. diff --git a/applications/nrf_desktop/doc/passkey.rst b/applications/nrf_desktop/doc/passkey.rst index 2828d80d19b2..ad544e092f6c 100644 --- a/applications/nrf_desktop/doc/passkey.rst +++ b/applications/nrf_desktop/doc/passkey.rst @@ -28,17 +28,17 @@ The passkey input handling is based on ``button_event``. To configure the passkey module, complete the following steps: 1. Enable and configure the :ref:`caf_buttons`. -#. Enable the passkey module by using the :ref:`CONFIG_DESKTOP_PASSKEY_BUTTONS ` option. +#. Enable the passkey module by using the :ref:`CONFIG_DESKTOP_PASSKEY_BUTTONS ` Kconfig option. #. Define the maximum number of digits in the passkey by using the :ref:`CONFIG_DESKTOP_PASSKEY_MAX_LEN ` option. #. Define the IDs of the keys used by the passkey module in the :file:`passkey_buttons_def.h` file located in the board-specific directory in the :file:`configuration` directory. You must define the IDs of the following keys: - * Keys used to input the digits. + * Keys used to enter the digits. * Keys used to confirm the input. - * Keys used to remove the last digit (short-press removes only the last digit, but if the key is held for longer than 2 seconds, the whole input is cleared). + * Keys used to remove the last digit (short-press removes only the last digit, but if the key is held for longer than two seconds, the whole input is cleared). - You can define multiple sets of keys used to input the digits, but every set should contain keys used to input every digit. - This is to ensure that the user will be able to input the passkey. + You can define multiple sets of keys used to enter the digits, but every set should contain keys used to enter every digit. + This is to ensure that you can enter the passkey. The index of the key ID in the input configuration array represents the digit. The example configuration of the module can be found in the :file:`configuration/nrf52kbd_nrf52832/passkey_buttons_def.h` file. diff --git a/applications/nrf_desktop/doc/qos.rst b/applications/nrf_desktop/doc/qos.rst index a0690585289d..3ac2613d567d 100644 --- a/applications/nrf_desktop/doc/qos.rst +++ b/applications/nrf_desktop/doc/qos.rst @@ -32,9 +32,9 @@ Module events Configuration ************* -The module requires the basic Bluetooth® configuration, as described in :ref:`nrf_desktop_bluetooth_guide`. +The module requires the basic Bluetooth configuration, as described in :ref:`nrf_desktop_bluetooth_guide`. -The module is enabled with :ref:`CONFIG_DESKTOP_QOS_ENABLE ` option. +To enable the module, use the :ref:`CONFIG_DESKTOP_QOS_ENABLE ` Kconfig option. The module is available on the :ref:`peripheral devices ` only and requires the :ref:`nrf_desktop_ble_qos` to be enabled. Implementation details diff --git a/applications/nrf_desktop/doc/selector.rst b/applications/nrf_desktop/doc/selector.rst index 576dc8383371..30f45c1ed125 100644 --- a/applications/nrf_desktop/doc/selector.rst +++ b/applications/nrf_desktop/doc/selector.rst @@ -7,8 +7,8 @@ Selector module :local: :depth: 2 -The selector module is used to send ``selector_event`` that informs about the current selector state. -The module has one implementation, which uses hardware selectors (:file:`selector_hw.c`). +The selector module is used to send a ``selector_event`` that informs about the current selector state. +The module uses hardware selectors (:file:`selector_hw.c`). Module events ************* @@ -24,9 +24,9 @@ Configuration ************* The module implemented in :file:`selector_hw.c` uses the Zephyr :ref:`zephyr:gpio_api` driver to check the state of hardware selectors. -For this reason, you should set :kconfig:option:`CONFIG_GPIO` option. +For this reason, you must set the :kconfig:option:`CONFIG_GPIO` Kconfig option. -Set :ref:`CONFIG_DESKTOP_SELECTOR_HW_ENABLE ` option to enable the module. +To enable the module, use the :ref:`CONFIG_DESKTOP_SELECTOR_HW_ENABLE ` option. The configuration for this module is an array of :c:struct:`selector_config` pointers. The array is written in the :file:`selector_hw_def.h` file located in the board-specific directory in the application configuration directory. @@ -37,7 +37,7 @@ For every hardware selector, define the following parameters: * :c:member:`selector_config.pins_size` - Size of the array of :c:struct:`gpio_pin`. .. note:: - Each source of ``selector_event`` must have a unique ID to properly distinguish events from different sources. + Each source of a ``selector_event`` must have a unique ID to properly distinguish events from different sources. Implementation details ********************** @@ -49,8 +49,8 @@ The ``selector_event`` that the module sends to inform about the current hardwar When the application goes to sleep, selectors are not informing about the state change (interrupts are disabled). -If a selector is placed between states, it is in unknown state and ``selector_event`` is not sent. +If a selector is placed between states, it is in an unknown state and ``selector_event`` is not sent. -Recording of selector state changes is implemented using GPIO callbacks (:c:struct:`gpio_callback`) and work (:c:struct:`k_work_delayable`). +Recording of selector state changes is implemented using GPIO callbacks (:c:struct:`gpio_callback`) and a work (:c:struct:`k_work_delayable`). Each state change triggers an interrupt (GPIO interrupt for pin level high). -Callback of an interrupt submits work, which sends ``selector_event``. +The callback of an interrupt submits a work that sends the ``selector_event``. diff --git a/applications/nrf_desktop/doc/smp.rst b/applications/nrf_desktop/doc/smp.rst index da5f2ec8e3ed..837d9f9bea53 100644 --- a/applications/nrf_desktop/doc/smp.rst +++ b/applications/nrf_desktop/doc/smp.rst @@ -24,5 +24,5 @@ Module events Implementation details ********************** -nRF Desktop uses the |smp| from :ref:`lib_caf` (CAF). +nRF Desktop uses the |smp| from the :ref:`lib_caf` (CAF). See the :ref:`CAF module ` page for the implementation details and guide on how to perform the firmware update in the `nRF Connect Device Manager`_ application. diff --git a/applications/nrf_desktop/doc/swift_pair_app.rst b/applications/nrf_desktop/doc/swift_pair_app.rst index d25c04053683..da5bc21b070d 100644 --- a/applications/nrf_desktop/doc/swift_pair_app.rst +++ b/applications/nrf_desktop/doc/swift_pair_app.rst @@ -7,7 +7,7 @@ Swift Pair module :local: :depth: 2 -The Swift Pair module is used to enable or disable the Swift Pair Bluetooth advertising payload depending on the selected Bluetooth peer (used local identity). +The Swift Pair module is used to enable or disable the Swift Pair Bluetooth® advertising payload depending on the selected Bluetooth peer (used local identity). The module distinguishes between the dongle peer and the general Bluetooth peers. Module events @@ -23,6 +23,9 @@ Module events Configuration ************* +To enable the module, use the :ref:`CONFIG_DESKTOP_SWIFT_PAIR ` Kconfig option. +This option automatically selects the :ref:`CONFIG_DESKTOP_BLE_DONGLE_PEER_ID_INFO ` Kconfig option to enable the dongle peer ID information event. + To use the Swift Pair module, you must enable the following Kconfig options: * :kconfig:option:`CONFIG_BT_ADV_PROV_SWIFT_PAIR` - The nRF Desktop's :ref:`nrf_desktop_ble_adv` uses the :ref:`bt_le_adv_prov_readme` to generate advertising and scan response data. @@ -36,16 +39,13 @@ To use the Swift Pair module, you must enable the following Kconfig options: * :ref:`CONFIG_DESKTOP_SWIFT_PAIR_ADV_GENERAL_PEER ` If the dongle peer is disabled, there is no reason to use the module. - The Swift Pair advertising data provider can be simply enabled or disabled during a build time through a dedicated Kconfig option. - -Set the :ref:`CONFIG_DESKTOP_SWIFT_PAIR ` Kconfig option to enable the module. -This option automatically selects the :ref:`CONFIG_DESKTOP_BLE_DONGLE_PEER_ID_INFO ` Kconfig option to enable the dongle peer ID information event. + You can enable or disable the Swift Pair advertising data provider during build time through a dedicated Kconfig option. Implementation details ********************** -The module is an early subscriber for :c:struct:`ble_peer_operation_event`. +The module is an early subscriber for a :c:struct:`ble_peer_operation_event`. This allows the module to enable or disable the Swift Pair advertising payload just before the Bluetooth advertising starts. -The module is a subscriber for :c:struct:`ble_dongle_peer_event`. +The module is a subscriber for a :c:struct:`ble_dongle_peer_event`. This allows the module to track the application local identity of the dongle peer. diff --git a/applications/nrf_desktop/doc/usb_state.rst b/applications/nrf_desktop/doc/usb_state.rst index c7de61d682ef..7b5db06bff4f 100644 --- a/applications/nrf_desktop/doc/usb_state.rst +++ b/applications/nrf_desktop/doc/usb_state.rst @@ -23,26 +23,26 @@ Module events Configuration ************* -The module is enabled by selecting the :ref:`CONFIG_DESKTOP_USB_ENABLE ` option. +To enable the module, use the :ref:`CONFIG_DESKTOP_USB_ENABLE ` Kconfig option. The :ref:`CONFIG_DESKTOP_USB_ENABLE ` option is implied by the :ref:`CONFIG_DESKTOP_ROLE_HID_DONGLE ` option. The module is enabled by default for the nRF Desktop dongles because the dongles forward the HID data to the host connected over USB. See the :ref:`nrf_desktop_hid_configuration` documentation for details. -The module can be used with either the USB legacy stack or the USB next stack. -The USB stack is selected by enabling one of the following Kconfig choice options: +You can use the module with either the USB legacy stack or the USB next stack. +To select the USB stack, enable one of the following Kconfig choice options: * :ref:`CONFIG_DESKTOP_USB_STACK_LEGACY ` The option enables USB legacy stack (:kconfig:option:`CONFIG_USB_DEVICE_STACK`). The USB legacy stack is used by default. * :ref:`CONFIG_DESKTOP_USB_STACK_NEXT ` The option enables USB next stack (:kconfig:option:`CONFIG_USB_DEVICE_STACK_NEXT`). - This is the only USB stack that supports USB High-Speed and the nRF54H20 platform. + This is the only USB stack that supports USB High-Speed and the nRF54H20 devices. .. note:: - The USB next stack integration is :ref:`experimental `. - The HID boot protocol integration is not yet fully tested and may not work properly. - The secondary image slot background erase in :ref:`nrf_desktop_dfu` may cause missing USB HID subscriptions after a USB cable is attached. + The USB next stack integration is :ref:`experimental `. + The HID boot protocol integration is not yet fully tested and may not work properly. + The secondary image slot background erase in :ref:`nrf_desktop_dfu` may cause missing USB HID subscriptions after a USB cable is attached. Some of the properties are configured in the same way for both stacks, but part of the configuration is specific to the selected USB stack. See the following sections for details. @@ -102,10 +102,10 @@ See the subsections below for details. nRF Desktop peripheral ---------------------- -The nRF Desktop peripheral devices by default use only a single HID-class USB instance. +By default, the nRF Desktop peripheral devices use only a single HID-class USB instance. In that case, this instance is used for all the HID reports. -Enable :ref:`CONFIG_DESKTOP_USB_SELECTIVE_REPORT_SUBSCRIPTION ` to use more than one USB HID-class instance on the nRF Desktop peripheral. +Enable the :ref:`CONFIG_DESKTOP_USB_SELECTIVE_REPORT_SUBSCRIPTION ` Kconfig option to use more than one USB HID-class instance on the nRF Desktop peripheral. Make sure to configure additional HID-class USB instances and create an additional :file:`usb_state_def.h` header in the configuration. The header assigns HID input reports to the HID-class USB instances. A given HID report can be handled only by a single HID-class USB instance. @@ -143,14 +143,14 @@ The same instance is used after reconnection. USB HID configuration in USB legacy stack ----------------------------------------- -For the USB legacy stack, the :ref:`CONFIG_DESKTOP_USB_STACK_LEGACY ` selects the required dependencies: :kconfig:option:`CONFIG_USB_DEVICE_STACK` and :kconfig:option:`CONFIG_USB_DEVICE_HID` Kconfig options. -The number of HID-class USB instances in the USB legacy stack is specified by :kconfig:option:`CONFIG_USB_HID_DEVICE_COUNT`. +For the USB legacy stack, the :ref:`CONFIG_DESKTOP_USB_STACK_LEGACY ` Kconfig option selects the required dependencies: :kconfig:option:`CONFIG_USB_DEVICE_STACK` and :kconfig:option:`CONFIG_USB_DEVICE_HID`. +The number of HID-class USB instances in the USB legacy stack is specified by the :kconfig:option:`CONFIG_USB_HID_DEVICE_COUNT` option. The default value of this option is updated to match requirements for either an nRF Desktop peripheral or a dongle. Low latency device configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The module sets the default value of :kconfig:option:`CONFIG_USB_HID_POLL_INTERVAL_MS` to ``1``. +The module sets the default value of the :kconfig:option:`CONFIG_USB_HID_POLL_INTERVAL_MS` Kconfig option to ``1``. For low latency of HID reports, the device requests a polling rate of 1 ms. Boot protocol configuration @@ -236,12 +236,12 @@ The module sends the report using :c:struct:`hid_report_event`, that is handled nRF54H20 support ================ -Due to the characteristics of the nRF54H20 USB Device Controller (UDC), following change has been made in the USB state module to support the nRF54H20 platform: +Due to the characteristics of the nRF54H20 USB Device Controller (UDC), following change has been made in the USB state module to support the nRF54H20 devices: * The module disables the USB stack when the USB cable is disconnected and enables the stack when the cable is connected. -This change is applicable to the nRF54H20 platform only. -It is necessary to ensure proper USB stack operation on the nRF54H20 platform. +This change is applicable to the nRF54H20 devices only. +It is necessary to ensure proper USB stack operation on the nRF54H20 devices. The :kconfig:option:`CONFIG_UDC_DWC2_USBHS_VBUS_READY_TIMEOUT` Kconfig option is set to a non-zero value to prevent the :c:func:`usbd_enable` function from blocking the application forever when the USB cable is not connected. Instead, the function returns an error on timeout. diff --git a/applications/nrf_desktop/doc/usb_state_pm.rst b/applications/nrf_desktop/doc/usb_state_pm.rst index 37a8cbdaf8fb..192ccb2a3b6f 100644 --- a/applications/nrf_desktop/doc/usb_state_pm.rst +++ b/applications/nrf_desktop/doc/usb_state_pm.rst @@ -23,8 +23,8 @@ Module events Configuration ************* -The module is enabled by selecting :ref:`CONFIG_DESKTOP_USB_PM_ENABLE ` option. -It depends on :ref:`CONFIG_DESKTOP_USB_ENABLE ` and :kconfig:option:`CONFIG_CAF_POWER_MANAGER` options. +To enable the module, use the :ref:`CONFIG_DESKTOP_USB_PM_ENABLE ` Kconfig option. +It depends on the options :ref:`CONFIG_DESKTOP_USB_ENABLE ` and :kconfig:option:`CONFIG_CAF_POWER_MANAGER`. The log level is inherited from the :ref:`nrf_desktop_usb_state`. diff --git a/applications/nrf_desktop/doc/watchdog.rst b/applications/nrf_desktop/doc/watchdog.rst index cc333d7eab1f..d5c70c45c701 100644 --- a/applications/nrf_desktop/doc/watchdog.rst +++ b/applications/nrf_desktop/doc/watchdog.rst @@ -25,23 +25,23 @@ Module events Configuration ************* +To enable the module, use the :ref:`CONFIG_DESKTOP_WATCHDOG_ENABLE ` Kconfig option. + The module uses Zephyr's :ref:`zephyr:watchdog_api` driver. For this reason, it automatically selects the :kconfig:option:`CONFIG_WATCHDOG` option. The ``watchdog0`` DTS alias determines the watchdog instance used by the module. -The module is enabled by the :ref:`CONFIG_DESKTOP_WATCHDOG_ENABLE ` option. - You must define :ref:`CONFIG_DESKTOP_WATCHDOG_TIMEOUT ` option. After this amount of time (in ms), the device will be restarted if the watchdog timer was not reset. .. note:: - The module is by default used only in the release configurations that do not enable logs. - When the :ref:`CONFIG_DESKTOP_LOG ` Kconfig option is enabled, enabling watchdog timer can cause losing logs, for example, when the logger is in the panic mode. + By default, the module is used only in the ``release`` configurations that do not enable logs. + When the :ref:`CONFIG_DESKTOP_LOG ` Kconfig option is set, enabling the watchdog timer can cause losing logs, for example, when the logger is in the panic mode. Implementation details ********************** -The watchdog timer is started when the :ref:`nrf_desktop_main` is ready (which is reported using :c:struct:`module_state_event`). +The watchdog timer is started when the :ref:`nrf_desktop_main` is ready (which is reported using the :c:struct:`module_state_event`). The module periodically resets the watchdog timer using :c:struct:`k_work_delayable`. -The work resubmits itself with delay equal to ``CONFIG_DESKTOP_WATCHDOG_TIMEOUT / 3``. -In case of the system hang, the work will not be processed, the watchdog timer will not be reset on time, and the system will be restarted. +The work resubmits itself with a delay equal to ``CONFIG_DESKTOP_WATCHDOG_TIMEOUT/3``. +In case of system hang, the work will not be processed, the watchdog timer will not be reset on time, and the system will be restarted. diff --git a/applications/nrf_desktop/doc/wheel.rst b/applications/nrf_desktop/doc/wheel.rst index c2ac76661450..a6b10983dbd2 100644 --- a/applications/nrf_desktop/doc/wheel.rst +++ b/applications/nrf_desktop/doc/wheel.rst @@ -22,7 +22,7 @@ Module events Configuration ************* -Enable the module with the :ref:`CONFIG_DESKTOP_WHEEL_ENABLE ` Kconfig option. +To enable the module, use the :ref:`CONFIG_DESKTOP_WHEEL_ENABLE ` Kconfig option. For detecting rotation, the wheel module uses Zephyr's QDEC driver. You can enable the module only when QDEC is configured in DTS and the Zephyr's QDEC driver is enabled with the :kconfig:option:`CONFIG_QDEC_NRFX` Kconfig option. @@ -31,10 +31,10 @@ If your board supports only one QDEC instance, the module relies on the ``qdec`` The QDEC DTS configuration specifies how many steps are done during one full angle. The sensor reports the rotation data in angle degrees. -Then, :ref:`CONFIG_DESKTOP_WHEEL_SENSOR_VALUE_DIVIDER ` (a wheel configuration option) converts the angle value into a value that is passed with a ``wheel_event`` to the destination module. +The :ref:`CONFIG_DESKTOP_WHEEL_SENSOR_VALUE_DIVIDER ` (a wheel configuration option) converts the angle value into a value that is passed with a ``wheel_event`` to the destination module. For example, configuring QDEC with 24 steps means that for each step the sensor will report a rotation of 15 degrees. -For HID to see this rotation as increment of one, :ref:`CONFIG_DESKTOP_WHEEL_SENSOR_VALUE_DIVIDER ` should be set to 15. +For HID to see this rotation as increment of one, set the :ref:`CONFIG_DESKTOP_WHEEL_SENSOR_VALUE_DIVIDER ` Kconfig option to 15. Implementation details ********************** @@ -49,10 +49,10 @@ The wheel module can be in the following states: When in ``STATE_ACTIVE``, the module enables the QDEC driver and waits for callback that indicates rotation. The QDEC driver may consume power during its operation. -If no rotation is detected after the time specified in :ref:`CONFIG_DESKTOP_WHEEL_SENSOR_IDLE_TIMEOUT `, the wheel module switches to ``STATE_ACTIVE_IDLE``, in which QDEC is disabled. -In this state, the rotation is detected using GPIO interrupts. -When the rotation is detected, the module switches back to ``STATE_ACTIVE``. +If no rotation is detected after the time specified by the :ref:`CONFIG_DESKTOP_WHEEL_SENSOR_IDLE_TIMEOUT ` Kconfig option, the wheel module switches to ``STATE_ACTIVE_IDLE``, in which QDEC is disabled. +In this state, rotation is detected using GPIO interrupts. +When rotation is detected, the module switches back to ``STATE_ACTIVE``. -When the system enters the low power state, the wheel module goes to ``STATE_SUSPENDED``. -In this state, the rotation is detected using the GPIO interrupts. +When the system enters the low power state, the wheel module switches to ``STATE_SUSPENDED``. +In this state, rotation is detected using the GPIO interrupts. The module issues a system wake-up event on wheel movement. diff --git a/doc/nrf/libraries/caf/ble_adv.rst b/doc/nrf/libraries/caf/ble_adv.rst index c25165cea7ff..aa75583bb813 100644 --- a/doc/nrf/libraries/caf/ble_adv.rst +++ b/doc/nrf/libraries/caf/ble_adv.rst @@ -92,12 +92,12 @@ During the grace period, Swift Pair data is removed from the advertising packet This is done to ensure that the user does not try to connect to the device that is no longer available. .. note:: - Make sure that :kconfig:option:`CONFIG_CAF_BLE_ADV_GRACE_PERIOD` Kconfig option is enabled if both following conditions are met: + Make sure that the :kconfig:option:`CONFIG_CAF_BLE_ADV_GRACE_PERIOD` Kconfig option is enabled if both following conditions are met: * Any of the providers requests the grace period. * :kconfig:option:`CONFIG_CAF_BLE_ADV_PM_EVENTS` is enabled. - The :kconfig:option:`CONFIG_CAF_BLE_ADV_GRACE_PERIOD` is enabled by default if the Swift Pair advertising data provider is enabled in the configuration. + The :kconfig:option:`CONFIG_CAF_BLE_ADV_GRACE_PERIOD` option is enabled by default if the Swift Pair advertising data provider is enabled in the configuration. Force power down on bonded peer power off ----------------------------------------- @@ -153,4 +153,4 @@ Grace period with synchronized updates of RPA and advertising data ================================================================== With both the :kconfig:option:`CONFIG_CAF_BLE_ADV_GRACE_PERIOD` and the :kconfig:option:`CONFIG_CAF_BLE_ADV_ROTATE_RPA` options enabled, if the RPA rotation occurs in the grace period, it terminates the grace period prematurely. -This limitation is caused by the Bluetooth API, which doesn't allow to delay the RPA rotation. +This limitation is caused by the Bluetooth API, which does not allow delay in the RPA rotation. diff --git a/doc/nrf/libraries/caf/ble_bond.rst b/doc/nrf/libraries/caf/ble_bond.rst index 263b21a56fa6..68f1098cf15c 100644 --- a/doc/nrf/libraries/caf/ble_bond.rst +++ b/doc/nrf/libraries/caf/ble_bond.rst @@ -23,8 +23,8 @@ Before using the module make sure that the following Kconfig options are enabled The device must be Bluetooth bondable and bonds must be stored in the non-volatile memory (settings). The :ref:`caf_settings_loader` is used to load content of the settings area during boot. -The |ble_bond| is enabled using :kconfig:option:`CONFIG_CAF_BLE_BOND`. -This Kconfig option selects :kconfig:option:`CONFIG_CAF_BLE_BOND_SUPPORTED` option to indicate that the |ble_bond| is implemented in the application. +To enable the |ble_bond|, use the :kconfig:option:`CONFIG_CAF_BLE_BOND` Kconfig option. +This option selects the :kconfig:option:`CONFIG_CAF_BLE_BOND_SUPPORTED` option to indicate that the |ble_bond| is implemented in the application. Enabling bond erase =================== @@ -42,15 +42,16 @@ Complete the following steps to enable bond erase: * :kconfig:option:`CONFIG_CAF_BLE_BOND_PEER_ERASE_CLICK_LONG` - :c:enumerator:`CLICK_LONG`, * :kconfig:option:`CONFIG_CAF_BLE_BOND_PEER_ERASE_CLICK_DOUBLE` - :c:enumerator:`CLICK_DOUBLE`. -#. By default, detection of the specific click for a specific button always triggers the bond erase. - Set :kconfig:option:`CONFIG_CAF_BLE_BOND_PEER_ERASE_CLICK_TIMEOUT` to specify the waiting time for detecting the button click after boot. + By default, detection of the specific click for a specific button always triggers the bond erase. + +#. Set :kconfig:option:`CONFIG_CAF_BLE_BOND_PEER_ERASE_CLICK_TIMEOUT` to specify the waiting time for detecting the button click after boot. The timeout is specified in milliseconds. The button click is ignored if it occurs after the timeout. Implementation details ********************** -The |ble_bond| can be used as a default implementation of Bluetooth LE bond functionality for simple applications. +You can use the |ble_bond| as a default implementation of Bluetooth LE bond functionality for simple applications. The module does not broadcast information about performed Bluetooth LE peer operations using :c:struct:`ble_peer_operation_event`. The module assumes that only default Bluetooth local identity is used. diff --git a/doc/nrf/libraries/caf/ble_smp.rst b/doc/nrf/libraries/caf/ble_smp.rst index 258e8963d331..393178e69145 100644 --- a/doc/nrf/libraries/caf/ble_smp.rst +++ b/doc/nrf/libraries/caf/ble_smp.rst @@ -28,12 +28,11 @@ To use the module, you must enable the following Kconfig options: Enabling remote OS management ============================= -The |smp| supports registering OS management handlers automatically, which you can enable using the following Kconfig option: - -* :kconfig:option:`CONFIG_MCUMGR_GRP_OS` - This option enables MCUmgr OS management handlers. - Use these handlers to remotely trigger the device reboot after the image transfer is completed. - After the reboot, the device starts using the new firmware. - One of the applications that support the remote reboot functionality is `nRF Connect for Mobile`_. +The |smp| supports registering OS management handlers automatically. +You can enable this using the :kconfig:option:`CONFIG_MCUMGR_GRP_OS` Kconfig option. +Use these handlers to remotely trigger the device reboot after the image transfer is completed. +After the reboot, the device starts using the new firmware. +One of the applications that support the remote reboot functionality is `nRF Connect for Mobile`_. Implementation details ********************** @@ -44,7 +43,7 @@ The module registers itself as the final subscriber of the event to track the nu If a :c:struct:`ble_smp_transfer_event` was already submitted but not processed, the module desists from submitting a subsequent event. After the previously submitted event is processed, the module submits a subsequent event when the :c:func:`upload_confirm_cb` callback is called. -The application user must not perform more than one firmware upgrade at a time. +Do not perform more than one firmware upgrade at a time. The modification of the data by multiple application modules can result in a broken image that is going to be rejected by the bootloader. After building your application with the |smp| enabled, the :file:`dfu_application.zip` archive is generated in the build directory. diff --git a/doc/nrf/libraries/caf/ble_state_pm.rst b/doc/nrf/libraries/caf/ble_state_pm.rst index f06600a1dbf8..30a6008765f0 100644 --- a/doc/nrf/libraries/caf/ble_state_pm.rst +++ b/doc/nrf/libraries/caf/ble_state_pm.rst @@ -7,19 +7,19 @@ CAF: Bluetooth state power manager module :local: :depth: 2 -The Bluetooth® state power manager module is a minor module that counts the number of active Bluetooth® connections and imposes a :ref:`power manager module ` power level restriction if there is at least one active connection. +The Bluetooth® state power manager module is a minor module that counts the number of active Bluetooth connections and imposes a :ref:`power manager module ` power level restriction if there is at least one active connection. Configuration ************* -The module is enabled by selecting :kconfig:option:`CONFIG_CAF_BLE_STATE_PM`. -It depends on :kconfig:option:`CONFIG_CAF_BLE_STATE` and :kconfig:option:`CONFIG_CAF_POWER_MANAGER`. +To enable the module, select the :kconfig:option:`CONFIG_CAF_BLE_STATE_PM` Kconfig option. +It depends on the :kconfig:option:`CONFIG_CAF_BLE_STATE` and :kconfig:option:`CONFIG_CAF_POWER_MANAGER` options. Implementation details ********************** The module reacts only to :c:struct:`ble_peer_event`. -Upon the reception of the event, the module checks if the Bluetooth® peer is connected or disconnected. +Upon the reception of the event, the module checks if the Bluetooth peer is connected or disconnected. It then counts the active connections. Depending on the count result: diff --git a/doc/nrf/libraries/caf/click_detector.rst b/doc/nrf/libraries/caf/click_detector.rst index a9de412c7a4c..36f4ae2e51f3 100644 --- a/doc/nrf/libraries/caf/click_detector.rst +++ b/doc/nrf/libraries/caf/click_detector.rst @@ -17,7 +17,7 @@ To use the module, you must enable the following Kconfig options: * :kconfig:option:`CONFIG_CAF_CLICK_DETECTOR` - This option enables the |click_detector|. * :kconfig:option:`CONFIG_CAF_BUTTON_EVENTS` - This option enables the ``button_event`` that is required for the |click_detector| to work. -In addition to :kconfig:option:`CONFIG_CAF_CLICK_DETECTOR`, the following Kconfig options are available for the module: +In addition, the following Kconfig options are available for the module: * :kconfig:option:`CONFIG_CAF_CLICK_DETECTOR_DEF_PATH` * :kconfig:option:`CONFIG_CAF_CLICK_DETECTOR_PM_EVENTS` @@ -27,7 +27,7 @@ Adding module configuration file In addition to setting the Kconfig options, you must also add a module configuration file that contains an array of :c:struct:`click_detector_config`. -To do so, complete the following steps: +Complete the following steps: 1. Add a file that defines the following information for every ``key_id`` that should be handled by the |click_detector| in an array of :c:struct:`click_detector_config`: @@ -80,6 +80,6 @@ The exact values of time intervals for click types are defined in the :file:`sub Power management states ======================= -If the option :kconfig:option:`CONFIG_CAF_CLICK_DETECTOR_PM_EVENTS` is enabled, the module can react to power management events. +If the :kconfig:option:`CONFIG_CAF_CLICK_DETECTOR_PM_EVENTS` Kconfig option is enabled, the module can react to power management events. The module stops tracing of key states when ``power_down_event`` is received. The module starts operating again when ``wake_up_event`` is received. diff --git a/doc/nrf/libraries/caf/leds.rst b/doc/nrf/libraries/caf/leds.rst index 2df53b6aaffd..818887d607e0 100644 --- a/doc/nrf/libraries/caf/leds.rst +++ b/doc/nrf/libraries/caf/leds.rst @@ -44,9 +44,8 @@ To use the module, you must fulfill the following requirements: #. Configure LEDs in DTS. See `Configuring LEDs in DTS`_ for details. -The following Kconfig options are also available for this module: - -* :kconfig:option:`CONFIG_CAF_LEDS_PM_EVENTS` - This option enables the reaction to `Power management events`_. +The :kconfig:option:`CONFIG_CAF_LEDS_PM_EVENTS` Kconfig option is also available for this module. +It enables the reaction to `Power management events`_. .. note:: The GPIO-based LED driver implementation supports only turning LED on or off. diff --git a/doc/nrf/libraries/caf/net_state.rst b/doc/nrf/libraries/caf/net_state.rst index 59920699feed..b56b0b12d5d9 100644 --- a/doc/nrf/libraries/caf/net_state.rst +++ b/doc/nrf/libraries/caf/net_state.rst @@ -13,14 +13,14 @@ The module provides different backends for available networks (like LTE or OpenT Configuration ************* -You can enable |net_state| by selecting the :kconfig:option:`CONFIG_CAF_NET_STATE` option in the configuration. +To enable the |net_state|, select the :kconfig:option:`CONFIG_CAF_NET_STATE` Kconfig option in the configuration. The module selects the backend based on the link layer enabled. Log information about connection waiting ======================================== -The option :kconfig:option:`CONFIG_CAF_LOG_NET_STATE_WAITING` enables periodically logging message, while the module is waiting for network connection. -The period between logs may be configured by :kconfig:option:`CONFIG_CAF_LOG_NET_STATE_WAITING_PERIOD`. +The :kconfig:option:`CONFIG_CAF_LOG_NET_STATE_WAITING` Kconfig option enables periodic message logging, while the module is waiting for network connection. +To configure the period between logs, use the :kconfig:option:`CONFIG_CAF_LOG_NET_STATE_WAITING_PERIOD` option. Implementation details ********************** @@ -34,4 +34,4 @@ The following network states are available: * :c:enumerator:`NET_STATE_CONNECTED` - Network interface is connected. :c:enumerator:`NET_STATE_CONNECTED` means that IP packets can be transmitted. -For example, in case of a Thread network, this means not only that the connection to the mesh network is established, but also that the Border Router is working and it is possible to transfer data. +For example, in a Thread network, this means not only that the connection to the mesh network is established, but also that the Border Router is working and it is possible to transfer data. diff --git a/doc/nrf/libraries/caf/power_manager.rst b/doc/nrf/libraries/caf/power_manager.rst index c035eaf50f49..bde6167910c1 100644 --- a/doc/nrf/libraries/caf/power_manager.rst +++ b/doc/nrf/libraries/caf/power_manager.rst @@ -13,22 +13,22 @@ The module achieves this reduction by switching to low power modes when the devi Configuration ************* -You can enable the |power_manager| by selecting the :kconfig:option:`CONFIG_CAF_POWER_MANAGER` option in the configuration. +To enable the |power_manager|, select the :kconfig:option:`CONFIG_CAF_POWER_MANAGER` Kconfig option in the configuration. This module uses Zephyr's :ref:`zephyr:pm_api` subsystem. Timeout configuration options ============================= -With the :kconfig:option:`CONFIG_CAF_POWER_MANAGER_TIMEOUT` configuration option, you can set the period of time after which the application enters the low power mode. +With the :kconfig:option:`CONFIG_CAF_POWER_MANAGER_TIMEOUT` Kconfig option, you can set the period of time after which the application enters the low power mode. By default, the timeout is set to 120 seconds. -The :kconfig:option:`CONFIG_CAF_POWER_MANAGER_ERROR_TIMEOUT` sets the period of time after which the device is turned off upon an internal error. +The :kconfig:option:`CONFIG_CAF_POWER_MANAGER_ERROR_TIMEOUT` option sets the period of time after which the device is turned off upon an internal error. Optional boolean for keeping the system on ========================================== -The :kconfig:option:`CONFIG_CAF_POWER_MANAGER_STAY_ON` lets the system stay on also when there are no active connections. +The :kconfig:option:`CONFIG_CAF_POWER_MANAGER_STAY_ON` Kconfig option lets the system stay on also when there are no active connections. For more information about configuration options, check the help in the configuration tool. @@ -37,7 +37,7 @@ Implementation details The |power_manager| is started when the "main" is ready (which is reported using :c:struct:`module_state_event`). -When started, it can do the following operations: +When started, it can perform the following operations: * Manage `Power states`_ * Trigger `Switching to low power`_ @@ -60,7 +60,7 @@ The |power_manager| takes control of the overall operating system power state. Power manager state handling in CAF -See the following section for more details about how the application state converts to the system power state. +See the following sections for more details about how the application state converts to the system power state. Idle ---- @@ -127,14 +127,14 @@ Some modules might not be ready to switch to the lower power state. In such case, the module that is not yet ready should consume the :c:struct:`power_down_event` and change its internal state, so that it enters the low power state when ready. After entering the low power state, each module must report this by sending a :c:struct:`module_state_event`. -The |power_manager| continues with the low power state change when it gets a notification that the module switched to the low power. +The |power_manager| continues with the low power state change when it gets a notification indicating that the module switched to the low power. Only after all modules confirmed that they have entered the low power state (by not consuming the :c:struct:`power_down_event`), the |power_manager| sets the required application's state. If a disconnection happens while the device is in the suspended state, the |power_manager| switches the application to the off state. However, the application can also be configured to keep the system in the suspended state when there are no active connections, instead of switching to the off state. -To select this behavior, use the :kconfig:option:`CONFIG_CAF_POWER_MANAGER_STAY_ON` configuration option. +To select this behavior, use the :kconfig:option:`CONFIG_CAF_POWER_MANAGER_STAY_ON` Kconfig option. Wake-up scenarios ================= @@ -157,7 +157,7 @@ This also restarts the power-down counter if the device is not connected through Wake-up from the off state -------------------------- -In the off state, the CPU is not running and the CPU reboot is required. +In the off state, the CPU is not running and a CPU reboot is required. Before the application enters the off state, at least one module must configure the peripheral under its control, so that it issues a hardware-related event capable of rebooting the CPU (that is, capable of leaving the CPU off mode). After the reboot, the application initializes itself again. diff --git a/doc/nrf/libraries/caf/sensor_data_aggregator.rst b/doc/nrf/libraries/caf/sensor_data_aggregator.rst index 3d721b655c2a..1ab4a01b70de 100644 --- a/doc/nrf/libraries/caf/sensor_data_aggregator.rst +++ b/doc/nrf/libraries/caf/sensor_data_aggregator.rst @@ -7,7 +7,7 @@ CAF: Sensor data aggregator module :local: :depth: 2 -The |sensor_data_aggregator| of the :ref:`lib_caf` (CAF) is a simple module responsible for aggregating sensor data in form of ``sensor_event`` and passing them further in packages. +The |sensor_data_aggregator| of the :ref:`lib_caf` (CAF) is responsible for aggregating sensor data in form of ``sensor_event`` and passing them further in packages. It can be used in both single-core and multi-core SoCs. When used with multi-core SoCs, the |sensor_data_aggregator| can reduce power consumption. @@ -16,7 +16,7 @@ One core gathers data from sensors and when there is sufficient data to analyze, Configuration ************* -To enable the |sensor_data_aggregator|,select the :kconfig:option:`CONFIG_CAF_SENSOR_DATA_AGGREGATOR` Kconfig option. +To enable the |sensor_data_aggregator|, select the :kconfig:option:`CONFIG_CAF_SENSOR_DATA_AGGREGATOR` Kconfig option. To use the module, you must complete the following steps: @@ -24,7 +24,7 @@ To use the module, you must complete the following steps: #. If you are using multi-core SoC and want to receive aggregated data on another core, on the second core enable the :kconfig:option:`CONFIG_CAF_SENSOR_DATA_AGGREGATOR_EVENTS` option. #. Enable aggregator in devicetree file that describes the aggregator parameters you can use, for example :file:`app.overlay` file. Each aggregator should be placed as a separate node. - For example, the file content could look like follows: + For example, the file content could look like this: .. code-block:: devicetree @@ -51,7 +51,7 @@ The aggregator is defined as a separate node in the devicetree and consists of t * ``sensor_descr`` - This parameter represents the description of the sensor and should be the same as the description in the :ref:`caf_sensor_manager`. * ``buf_data_length`` - This parameter represents the length of the buffer in bytes. Its default value is ``120``. - You should set the value as a multiple of sensor sample size times the size of :c:struct:`sensor_value` (``i*sample_size*sizeof(struct sensor_value)``). + Set the value as a multiple of sensor sample size times the size of :c:struct:`sensor_value` (``i*sample_size*sizeof(struct sensor_value)``). * ``sample_size`` - This parameter represents the sensor sample size and is expressed in ``sensor_value`` per sample. Its default value is ``1``. * ``buf_count`` - This parameter represents the number of buffers in the aggregator. @@ -68,12 +68,12 @@ Implementation details * :c:struct:`sensor_data_aggregator_release_buffer_event`. The |sensor_data_aggregator| gathers data from :c:struct:`sensor_event` and stores the data in an active :c:struct:`aggregator_buffer`. -When buffer is full, the |sensor_data_aggregator| sends the buffer to :c:struct:`sensor_data_aggregator_event` struct. +When the buffer is full, the |sensor_data_aggregator| sends the buffer to :c:struct:`sensor_data_aggregator_event` structure. Then module searches for the next free :c:struct:`aggregator_buffer` and sets it as an active buffer. After changing the sensor state and receiving :c:struct:`sensor_state_event`, the |sensor_data_aggregator| sends the data that is gathered in the active buffer. -After receiving :c:struct:`sensor_data_aggregator_release_buffer_event`, the |sensor_data_aggregator| sets :c:struct:`aggregator_buffer` to free state. +After receiving the :c:struct:`sensor_data_aggregator_release_buffer_event`, the |sensor_data_aggregator| sets the :c:struct:`aggregator_buffer` to free state. -Several buffers can be reduced to one, in case of a situation where the sampling period is greater than the time needed to send and process :c:struct:`sensor_data_aggregator_event`. -In the situation when sampling is much faster than the time needed to send and process :c:struct:`sensor_data_aggregator_event`, the number of buffers should be increased. +Several buffers can be reduced to one, when the sampling period is greater than the time needed to send and process :c:struct:`sensor_data_aggregator_event`. +When sampling is much faster than the time needed to send and process the :c:struct:`sensor_data_aggregator_event`, the number of buffers should be increased. diff --git a/doc/nrf/libraries/caf/sensor_manager.rst b/doc/nrf/libraries/caf/sensor_manager.rst index 78a109e55b5a..1509fcefd253 100644 --- a/doc/nrf/libraries/caf/sensor_manager.rst +++ b/doc/nrf/libraries/caf/sensor_manager.rst @@ -28,7 +28,7 @@ The following Kconfig options are also available for the module: * :kconfig:option:`CONFIG_CAF_SENSOR_MANAGER_PM` * :kconfig:option:`CONFIG_CAF_SENSOR_MANAGER_ACTIVE_PM` -To use the module, you must complete the following requirements: +To use the module, complete the following requirements: 1. Physically connect the sensor. #. Add and enable the sensor in the devicetree file. @@ -56,7 +56,7 @@ To use the module, you must complete the following requirements: * :c:member:`sm_sensor_config.sampling_period_ms` - Sensor sampling period, in milliseconds. * :c:member:`sm_sensor_config.active_events_limit` - Maximum number of unprocessed :c:struct:`sensor_event`. - For example, the file content could look like follows: + For example, the file content could look like this: .. code-block:: c @@ -118,7 +118,7 @@ To use the sensor trigger, complete the following steps: * :c:member:`sm_trigger.activation.thresh` - Sensor trigger activation threshold. * :c:member:`sm_trigger.activation.timeout_ms` - Time after which the sensor is put to sleep. - For example, the extended configuration file for the LIS2DH accelerometer could look like follows: + For example, the extended configuration file for the LIS2DH accelerometer could look like this: .. code-block:: c @@ -177,7 +177,7 @@ To manually configure the passive power management functionality, complete the f 1. Enable :kconfig:option:`CONFIG_CAF_SENSOR_MANAGER_PM` Kconfig option. #. Extend the module configuration file of the sensor of your choice by adding :c:member:`sm_sensor_config.suspend` in an array of :c:struct:`sm_sensor_config`. - For example, the extended configuration file for the LIS2DH accelerometer could look like follows: + For example, the extended configuration file for the LIS2DH accelerometer could look like this: .. code-block:: c @@ -214,7 +214,7 @@ Implementation details ********************** The |sensor_manager| starts in reaction to :c:struct:`module_state_event`. -When started, it can do the following operations: +When started, it can perform the following operations: * Periodically sample the configured sensors. * Submit :c:struct:`sensor_event` when the sensor channels are sampled. @@ -222,19 +222,19 @@ When started, it can do the following operations: The |sensor_manager| samples sensors periodically, according to the configuration specified for each sensor. Sampling of the sensors is done from a dedicated preemptive thread. -You can change the thread priority by setting the :kconfig:option:`CONFIG_CAF_SENSOR_MANAGER_THREAD_PRIORITY` Kconfig option. +To change the thread priority, by set the :kconfig:option:`CONFIG_CAF_SENSOR_MANAGER_THREAD_PRIORITY` Kconfig option. Use the preemptive thread priority to make sure that the thread does not block other operations in the system. For each sensor, the |sensor_manager| limits the number of :c:struct:`sensor_event` events that it submits, but whose processing has not been completed. This is done to prevent out-of-memory error if the system workqueue is blocked. The limit value for the maximum number of unprocessed events for each sensor is placed in the :c:member:`sm_sensor_config.active_events_limit` structure field in the configuration file. The ``active_sensor_events_cnt`` counter is incremented when :c:struct:`sensor_event` is sent and decremented when the event is processed by the |sensor_manager| that is the final subscriber of the event. -A situation can occur that the ``active_sensor_events_cnt`` counter will already be decremented but the memory allocated by the event would not yet be freed. +A situation can occur that the ``active_sensor_events_cnt`` counter is already decremented but the memory allocated by the event would not yet be freed. Because of this behavior, the maximum number of allocated sensor events for the given sensor is equal to :c:member:`sm_sensor_config.active_events_limit` plus one. The dedicated thread uses its own thread stack. -You can change the size of the stack by setting the :kconfig:option:`CONFIG_CAF_SENSOR_MANAGER_THREAD_STACK_SIZE` Kconfig option. -The thread stack size must be big enough for the sensors used. +To change the size of the stack, set the :kconfig:option:`CONFIG_CAF_SENSOR_MANAGER_THREAD_STACK_SIZE` Kconfig option. +The thread stack size must be large enough for the sensors used. Sensor state events =================== @@ -256,15 +256,15 @@ The following figure shows the possible state transitions. The |sensor_manager| submits :c:struct:`sensor_state_event` whenever the sensor state changes. Each sensor starts in the :c:enumerator:`SENSOR_STATE_DISABLED` state, which is not reported by the module. -Also, each sensor acts independently to others. +Also, each sensor acts independently. If one of the sensors reports an error, it does not stop the |sensor_manager| from sampling other sensors. After the initialization, each sensor changes its state to :c:enumerator:`SENSOR_STATE_ACTIVE` and start periodic sampling. -In case of an error sensor submits :c:struct:`sensor_state_event` with the :c:enumerator:`SENSOR_STATE_ERROR` state. +In case of an error, the sensor submits :c:struct:`sensor_state_event` with the :c:enumerator:`SENSOR_STATE_ERROR` state. -If the trigger functionality or :kconfig:option:`CONFIG_CAF_SENSOR_MANAGER_PM` is enabled the sensor can be put into the :c:enumerator:`SENSOR_STATE_SLEEP` state. +If the trigger functionality or :kconfig:option:`CONFIG_CAF_SENSOR_MANAGER_PM` is enabled, the sensor can be put into the :c:enumerator:`SENSOR_STATE_SLEEP` state. In this state, the sensor is not actively sampling and is not reporting any :c:struct:`sensor_event`. -If the sensor trigger fires or the :c:struct:`wake_up_event` comes, the sensor state changes to :c:enumerator:`SENSOR_STATE_ACTIVE` and periodic sampling is restarted. +If the sensor trigger fires or the :c:struct:`wake_up_event` is received, the sensor state changes to :c:enumerator:`SENSOR_STATE_ACTIVE` and periodic sampling is restarted. Sensor trigger activation ========================= @@ -272,14 +272,14 @@ Sensor trigger activation The sensor trigger is activated and the sensor is put to sleep if the values measured by the sensor do not deviate from the last sensor value by more than :c:member:`sm_trigger.activation.threshold` for the period of time specified in :c:member:`sm_trigger.activation.timeout_ms`. If the value measured by the sensor does not fit within the threshold, the last sensor value is updated and the sensor continues the sampling process. -The sensor trigger activation type is of the :c:enumerator:`ACT_TYPE_ABS` (Absolute deviation) type. +The sensor trigger activation type is :c:enumerator:`ACT_TYPE_ABS` (Absolute deviation). Passive power management ======================== If the :kconfig:option:`CONFIG_CAF_SENSOR_MANAGER_PM` Kconfig option is enabled, the sensors react to :c:struct:`power_down_event` and :c:struct:`wake_up_event`. -If a :c:struct:`power_down_event` comes when the sensor is in the :c:enumerator:`SENSOR_STATE_ACTIVE` state, the sensor state changes to :c:enumerator:`SENSOR_STATE_SLEEP` and sensor stops sampling. +If a :c:struct:`power_down_event` is received when the sensor is in the :c:enumerator:`SENSOR_STATE_ACTIVE` state, the sensor state changes to :c:enumerator:`SENSOR_STATE_SLEEP` and the sensor stops sampling. Depending on the trigger functionality configuration: @@ -289,7 +289,7 @@ Depending on the trigger functionality configuration: .. note:: |device_pm_note| -If a :c:struct:`wake_up_event` comes when the sensor is in the :c:enumerator:`SENSOR_STATE_SLEEP` state, the sensor switches to :c:enumerator:`SENSOR_STATE_ACTIVE` and starts actively sampling. +If a :c:struct:`wake_up_event` is received when the sensor is in the :c:enumerator:`SENSOR_STATE_SLEEP` state, the sensor switches to :c:enumerator:`SENSOR_STATE_ACTIVE` and starts active sampling. Depending on the trigger functionality configuration: @@ -299,16 +299,16 @@ Depending on the trigger functionality configuration: Active power management ======================= -If :kconfig:option:`CONFIG_CAF_SENSOR_MANAGER_ACTIVE_PM` is enabled, the sensor can submit :c:struct:`power_manager_restrict_event` and :c:struct:`wake_up_event`. +If the :kconfig:option:`CONFIG_CAF_SENSOR_MANAGER_ACTIVE_PM` Kconfig option is enabled, the sensor can submit :c:struct:`power_manager_restrict_event` and :c:struct:`wake_up_event`. -A :c:struct:`power_manager_restrict_event` restricts a power level to which the application can be put. +A :c:struct:`power_manager_restrict_event` restricts the power level to which the application can be put. It is submitted every time the allowed state changes. If there is any sensor that is in the :c:enumerator:`SENSOR_STATE_ACTIVE` state, the module power state is restricted to the :c:enumerator:`POWER_MANAGER_LEVEL_ALIVE` state. If all the sensors are in the :c:enumerator:`SENSOR_STATE_SLEEP` state and if at least one sensor has trigger activated, the power state is restricted to the :c:enumerator:`POWER_MANAGER_LEVEL_SUSPENDED` state. Having all the sensors sleeping and none of them with the trigger functionality enabled means that any power state is allowed. -If the sensor's trigger functionality is configured, each time the trigger is activated :c:struct:`wake_up_event` is created and sent to other modules. +If the sensor's trigger functionality is configured, each time the trigger is activated, a :c:struct:`wake_up_event` is created and sent to other modules. Sending :c:struct:`wake_up_event` to other modules results in waking up the whole system. @@ -317,7 +317,7 @@ Sending :c:struct:`wake_up_event` to other modules results in waking up the whol Changing sensor sample period ============================= -To change sensor sample period you have to send :c:struct:`set_sensor_period_event` with new period value in milliseconds. +To change the sensor sample period, you have to send :c:struct:`set_sensor_period_event` with new period value in milliseconds. To identify which sensor sampling period you want to change, set the sensor description in :c:struct:`set_sensor_period_event`. The following code shows an example of changing accelerometer sampling to 400 ms: diff --git a/doc/nrf/libraries/caf/settings_loader.rst b/doc/nrf/libraries/caf/settings_loader.rst index 126258b6bf23..cbb70a084386 100644 --- a/doc/nrf/libraries/caf/settings_loader.rst +++ b/doc/nrf/libraries/caf/settings_loader.rst @@ -7,7 +7,7 @@ CAF: Settings loader module :local: :depth: 2 -The |settings_loader| of the :ref:`lib_caf` (CAF) is a simple, stateless module responsible for calling the :c:func:`settings_load` function. +The |settings_loader| of the :ref:`lib_caf` (CAF) is a stateless module responsible for calling the :c:func:`settings_load` function. If any of the application modules relies on settings, this module ensures that the data stored in non-volatile memory is read after completing all necessary initialization. Configuration @@ -24,11 +24,11 @@ The following Kconfig options are also available for the module: * :kconfig:option:`CONFIG_CAF_SETTINGS_LOADER_USE_THREAD` * :kconfig:option:`CONFIG_CAF_SETTINGS_LOADER_THREAD_STACK_SIZE` -To use the module, you must complete the following steps: +To use the module, complete the following steps: 1. Enable the :kconfig:option:`CONFIG_CAF_SETTINGS_LOADER` and :kconfig:option:`CONFIG_SETTINGS` Kconfig options. #. Add the configuration file that implements the function :c:func:`get_req_modules`, which sets bits of modules that are required to be initialized before settings are loaded. - For example, the file content could look like follows: + For example, the file content could look like this: .. code-block:: c @@ -43,7 +43,7 @@ To use the module, you must complete the following steps: }; This function is called on the settings loader module initialization. -After each of modules that sets bit in :c:func:`get_req_modules` is initialized, the |settings_loader| calls :c:func:`settings_load` function and starts loading all the settings from non-volatile memory. +After each module that sets a bit in the :c:func:`get_req_modules` function is initialized, the |settings_loader| calls the :c:func:`settings_load` function and starts loading all settings from the non-volatile memory. File system as settings backend =============================== @@ -56,8 +56,8 @@ Implementation details Getting the required modules is wrapped into the :c:func:`get_req_modules` function due to implementation limitations. -Settings are loaded in the :ref:`app_event_manager` handler, which by default is invoked from a system workqueue context. +Settings are loaded in the :ref:`app_event_manager` handler that is invoked from a system workqueue context by default. This blocks the workqueue until the operation is finished. -You can set the :kconfig:option:`CONFIG_CAF_SETTINGS_LOADER_USE_THREAD` Kconfig option to load the settings in a separate thread in the background instead of using the system workqueue for that purpose. +Set the :kconfig:option:`CONFIG_CAF_SETTINGS_LOADER_USE_THREAD` Kconfig option to load the settings in a separate thread in the background instead of using the system workqueue for that purpose. This prevents blocking the system workqueue, but it requires creating an additional thread. The stack size for the background thread is defined in the :kconfig:option:`CONFIG_CAF_SETTINGS_LOADER_THREAD_STACK_SIZE` Kconfig option.