.. _paw3212:

PAW3212 driver
##############

.. contents::
   :local:
   :depth: 2

The PAW3212 driver implements a PAW3212 motion sensor driver that is compatible with Zephyr's :ref:`zephyr:sensor_api`.

The sensor driver supports the following features:

* Motion data readouts for X and Y axes
* :c:enum:`SENSOR_TRIG_DATA_READY` trigger
* Configuring attributes of the PAW3212 sensor

.. note::
  The PAW3212 driver is similar to :ref:`pmw3360`, but it allows customizing motion data length instead of CPI and downshift values, as detailed in `Kconfig configuration`_.
  Also, this sensor does not support burst mode.

Configuration
*************

To use the sensor, you must provide a valid hardware configuration of the sensor in the Devicetree Specification (DTS) and enable and configure the driver in Kconfig.

Devicetree Specification configuration
======================================

The following code snippet shows an example DTS configuration:

.. code-block:: devicetree

    &pinctrl {
        spi0_default_alt: spi0_default_alt {
            group1 {
                psels = <NRF_PSEL(SPI_SCK, 0, 10)>,
                        <NRF_PSEL(SPI_MISO, 0, 12)>,
                        <NRF_PSEL(SPI_MOSI, 0, 13)>;
            };
        };

        spi0_sleep_alt: spi0_sleep_alt {
            group1 {
                psels = <NRF_PSEL(SPI_SCK, 0, 16)>,
                        <NRF_PSEL(SPI_MISO, 0, 15)>,
                        <NRF_PSEL(SPI_MOSI, 0, 17)>;
                low-power-enable;
          };
        };
    };

    &spi0 {
        compatible = "nordic,nrf-spim";
        status = "okay";
        pinctrl-0 = <&spi0_default_alt>;
        pinctrl-1 = <&spi0_sleep_alt>;
        pinctrl-names = "default", "sleep";
        cs-gpios = <&gpio0 15 GPIO_ACTIVE_LOW>;

        paw3212@0 {
            compatible = "pixart,paw3212";
            reg = <0>;
            irq-gpios = <&gpio0 14 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>;
            spi-max-frequency = <2000000>;
        };
  };

The PAW3212 sensor node must meet the following requirements:

* It must be a child node of a SPI node.
* It must be compatible with ``pixart,paw3212``.

Moreover, you must configure the following parameters:

* Pins used by the SPI that are common for all devices connected to the bus (SCK, MISO and MOSI).

* Chip select (CS) pin for the PAW3212 motion sensor.
  GPIOs used as chip select for the devices connected to the SPI are defined as ``cs-gpios``.
  The ``@0`` in ``paw3212@0`` refers to the position of the chip select pin of the motion sensor in the array.
* Parameters inherited from the ``spi-device`` binding that are defined for every SPI device:

  * ``reg`` - The slave ID number the device has on a bus.
  * ``spi-max-frequency`` - Used for setting the bus clock frequency.

* Pin to which the motion sensor IRQ line is connected (``irq-gpios``).

See :ref:`zephyr:dt-guide` for more detailed information about the DTS data structure.

.. note::
   The motion sensor driver implementation does not benefit from the SPI context lock.
   The operation related to the PAW3212 motion sensor can be interrupted by data exchange with another sensor connected over the same SPI interface.
   If other sensors use the same SPI interface, you must ensure that SPI operations are not preempted.

Kconfig configuration
=====================

Use the following Kconfig options to configure the PAW3212 motion sensor:

* :kconfig:option:`CONFIG_PAW3212` - This option enables the PAW3212 motion sensor driver.
* :kconfig:option:`CONFIG_PAW3212_ORIENTATION_0`, :kconfig:option:`CONFIG_PAW3212_ORIENTATION_90`, :kconfig:option:`CONFIG_PAW3212_ORIENTATION_180`, or :kconfig:option:`CONFIG_PAW3212_ORIENTATION_270` - The selected choice option specifies the rotation of the PAW3212 motion sensor in degrees (clockwise), respectively 0, 90, 180, or 270 degrees.
* :kconfig:option:`CONFIG_PAW3212_8_BIT_MODE` or :kconfig:option:`CONFIG_PAW3212_12_BIT_MODE` - The selected choice option specifies the motion data length, respectively 8-bit or 12-bit.

See :ref:`kconfig_tips_and_tricks` for information about Kconfig.

Sensor API calls
****************

Read the following sections for information about the :ref:`zephyr:sensor_api` calls supported by the motion sensor.

.. note::
   Driver initialization is performed asynchronously using a delayed work that resubmits itself.
   This is done to prevent delaying system start.

   The sensor returns ``-EBUSY`` if the sensor API is used before the asynchronous initialization is completed.

Motion data reading
===================

Use the following operations to read the motion data:

* Fetch motion data using :c:enum:`SENSOR_CHAN_ALL`.
  Fetching sensor channels separately is not supported.
* Read data for motion in the X and Y axes using :c:enum:`SENSOR_CHAN_POS_DX` and :c:enum:`SENSOR_CHAN_POS_DY`, respectively.

Sensor trigger
==============

The sensor supports :c:enum:`SENSOR_TRIG_DATA_READY` trigger for :c:enum:`SENSOR_CHAN_ALL`.
The trigger handler is called when motion is detected.

Sensor attributes
=================

The sensor supports a custom set of attributes that are not part of generic sensor attributes defined by Zephyr's :ref:`zephyr:sensor_api` API.
The attributes are defined as private to the motion sensor in the sensor's header file.
See API documentation for details.

API documentation
*****************

| Header file: :file:`include/sensor/paw3212.h`
| Source file: :file:`drivers/sensor/paw3212/paw3212.c`

.. doxygengroup:: paw3212
   :project: nrf
   :members: