PMW3360 driver

The PMW3360 driver implements a PMW3360 motion sensor driver that is compatible with Zephyr’s Sensors.

The sensor driver supports the following features:

  • Motion data readouts for X and Y axes

  • SENSOR_TRIG_DATA_READY trigger

  • Configuring attributes of the PMW3360 sensor

Note

The PMW3360 driver is similar to PAW3212 driver, but it allows customizing CPI value and downshift time, as detailed in Kconfig configuration. The sensor also supports 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:

&pinctrl {
    spi1_default_alt: spi1_default_alt {
        group1 {
            psels = <NRF_PSEL(SPI_SCK, 0, 16)>,
                    <NRF_PSEL(SPI_MISO, 0, 15)>,
                    <NRF_PSEL(SPI_MOSI, 0, 17)>;
        };
    };

    spi1_sleep_alt: spi1_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;
      };
    };
};

&spi1 {
    compatible = "nordic,nrf-spim";
    status = "okay";
    pinctrl-0 = <&spi1_default_alt>;
    pinctrl-1 = <&spi1_sleep_alt>;
    pinctrl-names = "default", "sleep";
    cs-gpios = <&gpio0 13 0>;

    pmw3360@0 {
            compatible = "pixart,pmw3360";
            reg = <0>;
            irq-gpios = <&gpio0 21 0>;
            spi-max-frequency = <2000000>;
            label = "PMW3360";
    };
};

The PMW3360 sensor node must meet the following requirements:

  • It must be a child node of a SPI node.

  • It must be compatible with pixart,pmw3360.

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 PMW3360 motion sensor. GPIOs used as chip select for the devices connected to the SPI are defined as cs-gpios. The @0 in pmw3360@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.

    • label - Name of the device.

    • spi-max-frequency - Used for setting the bus clock frequency.

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

See Devicetree 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 PMW3360 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 PMW3360 motion sensor:

See Kconfig - Tips and Best Practices for information about Kconfig.

Sensor API calls

Read the following sections for information about the Sensors 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 SENSOR_CHAN_ALL. Fetching sensor channels separately is not supported.

  • Read data for motion in the X and Y axes using SENSOR_CHAN_POS_DX and SENSOR_CHAN_POS_DY, respectively.

Sensor trigger

The sensor supports SENSOR_TRIG_DATA_READY trigger for 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 Sensors API. The attributes are defined as private to the motion sensor in the sensor’s header file. See API documentation for details.

Burst mode

Driver uses burst mode for reading motion to improve data transfer speed.

API documentation

Header file: include/sensor/pmw3360.h
Source file: drivers/sensor/pmw3360/pmw3360.c
group pmw3360

PMW3360 motion sensor driver.

Enums

enum pmw3360_attribute

Sensor specific attributes of PMW3360.

Values:

enumerator PMW3360_ATTR_CPI

Sensor CPI for both X and Y axes.

enumerator PMW3360_ATTR_REST_ENABLE

Enable or disable sleep modes.

enumerator PMW3360_ATTR_RUN_DOWNSHIFT_TIME

Entering time from Run mode to REST1 mode [ms].

enumerator PMW3360_ATTR_REST1_DOWNSHIFT_TIME

Entering time from REST1 mode to REST2 mode [ms].

enumerator PMW3360_ATTR_REST2_DOWNSHIFT_TIME

Entering time from REST2 mode to REST3 mode [ms].

enumerator PMW3360_ATTR_REST1_SAMPLE_TIME

Sampling frequency time during REST1 mode [ms].

enumerator PMW3360_ATTR_REST2_SAMPLE_TIME

Sampling frequency time during REST2 mode [ms].

enumerator PMW3360_ATTR_REST3_SAMPLE_TIME

Sampling frequency time during REST3 mode [ms].