diff options
Diffstat (limited to 'Documentation/devicetree/bindings/iio')
9 files changed, 452 insertions, 26 deletions
diff --git a/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt b/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt index 93a0bd2efc05..4c0da8c74bb2 100644 --- a/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt +++ b/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt @@ -47,6 +47,12 @@ Required properties: Optional properties: - A pinctrl state named "default" for each ADC channel may be defined to set inX ADC pins in mode of operation for analog input on external pin. +- booster-supply: Phandle to the embedded booster regulator that can be used + to supply ADC analog input switches on stm32h7 and stm32mp1. +- vdd-supply: Phandle to the vdd input voltage. It can be used to supply ADC + analog input switches on stm32mp1. +- st,syscfg: Phandle to system configuration controller. It can be used to + control the analog circuitry on stm32mp1. Contents of a stm32 adc child node: ----------------------------------- diff --git a/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.txt b/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.txt deleted file mode 100644 index c52ea2126eaa..000000000000 --- a/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.txt +++ /dev/null @@ -1,26 +0,0 @@ -* Plantower PMS7003 particulate matter sensor - -Required properties: -- compatible: must one of: - "plantower,pms1003" - "plantower,pms3003" - "plantower,pms5003" - "plantower,pms6003" - "plantower,pms7003" - "plantower,pmsa003" -- vcc-supply: phandle to the regulator that provides power to the sensor - -Optional properties: -- plantower,set-gpios: phandle to the GPIO connected to the SET line -- reset-gpios: phandle to the GPIO connected to the RESET line - -Refer to serial/slave-device.txt for generic serial attached device bindings. - -Example: - -&uart0 { - air-pollution-sensor { - compatible = "plantower,pms7003"; - vcc-supply = <®_vcc5v0>; - }; -}; diff --git a/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.yaml b/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.yaml new file mode 100644 index 000000000000..a551d3101f93 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/chemical/plantower,pms7003.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Plantower PMS7003 air pollution sensor + +maintainers: + - Tomasz Duszynski <tduszyns@gmail.com> + +description: | + Air pollution sensor capable of measuring mass concentration of dust + particles. + +properties: + compatible: + enum: + - plantower,pms1003 + - plantower,pms3003 + - plantower,pms5003 + - plantower,pms6003 + - plantower,pms7003 + - plantower,pmsa003 + + vcc-supply: + description: regulator that provides power to the sensor + maxItems: 1 + + plantower,set-gpios: + description: GPIO connected to the SET line + maxItems: 1 + + reset-gpios: + description: GPIO connected to the RESET line + maxItems: 1 + +required: + - compatible + - vcc-supply + +examples: + - | + serial { + air-pollution-sensor { + compatible = "plantower,pms7003"; + vcc-supply = <®_vcc5v0>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/iio/imu/adi,adis16460.yaml b/Documentation/devicetree/bindings/iio/imu/adi,adis16460.yaml new file mode 100644 index 000000000000..0c53009ba7d6 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/imu/adi,adis16460.yaml @@ -0,0 +1,53 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/imu/adi,adis16460.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices ADIS16460 and similar IMUs + +maintainers: + - Dragos Bogdan <dragos.bogdan@analog.com> + +description: | + Analog Devices ADIS16460 and similar IMUs + https://www.analog.com/media/en/technical-documentation/data-sheets/ADIS16460.pdf + +properties: + compatible: + enum: + - adi,adis16460 + + reg: + maxItems: 1 + + spi-cpha: true + + spi-cpol: true + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + spi0 { + #address-cells = <1>; + #size-cells = <0>; + + imu@0 { + compatible = "adi,adis16460"; + reg = <0>; + spi-max-frequency = <5000000>; + spi-cpol; + spi-cpha; + interrupt-parent = <&gpio0>; + interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt b/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt index efec9ece034a..87407d110bb7 100644 --- a/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt +++ b/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt @@ -11,6 +11,8 @@ Required properties: "st,asm330lhh" "st,lsm6dsox" "st,lsm6dsr" + "st,lsm6ds3tr-c" + "st,ism330dhcx" - reg: i2c address of the sensor / spi cs line Optional properties: diff --git a/Documentation/devicetree/bindings/iio/light/noa1305.yaml b/Documentation/devicetree/bindings/iio/light/noa1305.yaml new file mode 100644 index 000000000000..17e7f140b69b --- /dev/null +++ b/Documentation/devicetree/bindings/iio/light/noa1305.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/light/noa1305.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ON Semiconductor NOA1305 Ambient Light Sensor + +maintainers: + - Martyn Welch <martyn.welch@collabora.com> + +description: | + Ambient sensing with an i2c interface. + + https://www.onsemi.com/pub/Collateral/NOA1305-D.PDF + +properties: + compatible: + enum: + - onnn,noa1305 + + reg: + maxItems: 1 + + vin-supply: + description: Regulator that provides power to the sensor + +required: + - compatible + - reg + +examples: + - | + i2c { + + #address-cells = <1>; + #size-cells = <0>; + + light@39 { + compatible = "onnn,noa1305"; + reg = <0x39>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/light/stk33xx.yaml b/Documentation/devicetree/bindings/iio/light/stk33xx.yaml new file mode 100644 index 000000000000..aae8a6d627c9 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/light/stk33xx.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/light/stk33xx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: | + Sensortek STK33xx I2C Ambient Light and Proximity sensor + +maintainers: + - Jonathan Cameron <jic23@kernel.org> + +description: | + Ambient light and proximity sensor over an i2c interface. + +properties: + compatible: + enum: + - sensortek,stk3310 + - sensortek,stk3311 + - sensortek,stk3335 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + + #address-cells = <1>; + #size-cells = <0>; + + stk3310@48 { + compatible = "sensortek,stk3310"; + reg = <0x48>; + interrupt-parent = <&gpio1>; + interrupts = <5 IRQ_TYPE_LEVEL_LOW>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/mount-matrix.txt b/Documentation/devicetree/bindings/iio/mount-matrix.txt new file mode 100644 index 000000000000..c3344ab509a3 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt @@ -0,0 +1,203 @@ +For discussion. Unclear are: +* is the definition of +/- values practical or counterintuitive? +* are the definitions unambiguous and easy to follow? +* are the examples correct? +* should we have HOWTO engineer a correct matrix for a new device (without comparing to a different one)? + +==== + + +Mounting matrix + +The mounting matrix is a device tree property used to orient any device +that produce three-dimensional data in relation to the world where it is +deployed. + +The purpose of the mounting matrix is to translate the sensor frame of +reference into the device frame of reference using a translation matrix as +defined in linear algebra. + +The typical usecase is that where a component has an internal representation +of the (x,y,z) triplets, such as different registers to read these coordinates, +and thus implying that the component should be mounted in a certain orientation +relative to some specific device frame of reference. + +For example a device with some kind of screen, where the user is supposed to +interact with the environment using an accelerometer, gyroscope or magnetometer +mounted on the same chassis as this screen, will likely take the screen as +reference to (x,y,z) orientation, with (x,y) corresponding to these axes on the +screen and (z) being depth, the axis perpendicular to the screen. + +For a screen you probably want (x) coordinates to go from negative on the left +to positive on the right, (y) from negative on the bottom to positive on top +and (z) depth to be negative under the screen and positive in front of it, +toward the face of the user. + +A sensor can be mounted in any angle along the axes relative to the frame of +reference. This means that the sensor may be flipped upside-down, left-right, +or tilted at any angle relative to the frame of reference. + +Another frame of reference is how the device with its sensor relates to the +external world, the environment where the device is deployed. Usually the data +from the sensor is used to figure out how the device is oriented with respect +to this world. When using the mounting matrix, the sensor and device orientation +becomes identical and we can focus on the data as it relates to the surrounding +world. + +Device-to-world examples for some three-dimensional sensor types: + +- Accelerometers have their world frame of reference toward the center of + gravity, usually to the core of the planet. A reading of the (x,y,z) values + from the sensor will give a projection of the gravity vector through the + device relative to the center of the planet, i.e. relative to its surface at + this point. Up and down in the world relative to the device frame of + reference can thus be determined. and users would likely expect a value of + 9.81 m/s^2 upwards along the (z) axis, i.e. out of the screen when the device + is held with its screen flat on the planets surface and 0 on the other axes, + as the gravity vector is projected 1:1 onto the sensors (z)-axis. + + If you tilt the device, the g vector virtually coming out of the display + is projected onto the (x,y) plane of the display panel. + + Example: + + ^ z: +g ^ z: > 0 + ! /! + ! x=y=0 / ! x: > 0 + +--------+ +--------+ + ! ! ! ! + +--------+ +--------+ + ! / + ! / + v v + center of center of + gravity gravity + + + If the device is tilted to the left, you get a positive x value. If you point + its top towards surface, you get a negative y axis. + + (---------) + ! ! y: -g + ! ! ^ + ! ! ! + ! ! + ! ! x: +g <- z: +g -> x: -g + ! 1 2 3 ! + ! 4 5 6 ! ! + ! 7 8 9 ! v + ! * 0 # ! y: +g + (---------) + + +- Magnetometers (compasses) have their world frame of reference relative to the + geomagnetic field. The system orientation vis-a-vis the world is defined with + respect to the local earth geomagnetic reference frame where (y) is in the + ground plane and positive towards magnetic North, (x) is in the ground plane, + perpendicular to the North axis and positive towards the East and (z) is + perpendicular to the ground plane and positive upwards. + + + ^^^ North: y > 0 + + (---------) + ! ! + ! ! + ! ! + ! ! > + ! ! > North: x > 0 + ! 1 2 3 ! > + ! 4 5 6 ! + ! 7 8 9 ! + ! * 0 # ! + (---------) + + Since the geomagnetic field is not uniform this definition fails if we come + closer to the poles. + + Sensors and driver can not and should not take care of this because there + are complex calculations and empirical data to be taken care of. We leave + this up to user space. + + The definition we take: + + If the device is placed at the equator and the top is pointing north, the + display is readable by a person standing upright on the earth surface, this + defines a positive y value. + + +- Gyroscopes detects the movement relative the device itself. The angular + velocity is defined as orthogonal to the plane of rotation, so if you put the + device on a flat surface and spin it around the z axis (such as rotating a + device with a screen lying flat on a table), you should get a negative value + along the (z) axis if rotated clockwise, and a positive value if rotated + counter-clockwise according to the right-hand rule. + + + (---------) y > 0 + ! ! v---\ + ! ! + ! ! + ! ! <--\ + ! ! ! z > 0 + ! 1 2 3 ! --/ + ! 4 5 6 ! + ! 7 8 9 ! + ! * 0 # ! + (---------) + + +So unless the sensor is ideally mounted, we need a means to indicate the +relative orientation of any given sensor of this type with respect to the +frame of reference. + +To achieve this, use the device tree property "mount-matrix" for the sensor. + +This supplies a 3x3 rotation matrix in the strict linear algebraic sense, +to orient the senor axes relative to a desired point of reference. This means +the resulting values from the sensor, after scaling to proper units, should be +multiplied by this matrix to give the proper vectors values in three-dimensional +space, relative to the device or world point of reference. + +For more information, consult: +https://en.wikipedia.org/wiki/Rotation_matrix + +The mounting matrix has the layout: + + (mxx, myx, mzx) + (mxy, myy, mzy) + (mxz, myz, mzz) + +Values are intended to be multiplied as: + + x' = mxx * x + myx * y + mzx * z + y' = mxy * x + myy * y + mzy * z + z' = mxz * x + myz * y + mzz * z + +It is represented as an array of strings containing the real values for +producing the transformation matrix. + +Examples: + +Identity matrix (nothing happens to the coordinates, which means the device was +mechanically mounted in an ideal way and we need no transformation): + +mount-matrix = "1", "0", "0", + "0", "1", "0", + "0", "0", "1"; + +The sensor is mounted 30 degrees (Pi/6 radians) tilted along the X axis, so we +compensate by performing a -30 degrees rotation around the X axis: + +mount-matrix = "1", "0", "0", + "0", "0.866", "0.5", + "0", "-0.5", "0.866"; + +The sensor is flipped 180 degrees (Pi radians) around the Z axis, i.e. mounted +upside-down: + +mount-matrix = "0.998", "0.054", "0", + "-0.054", "0.998", "0", + "0", "0", "1"; + +???: this does not match "180 degrees" - factors indicate ca. 3 degrees compensation diff --git a/Documentation/devicetree/bindings/iio/potentiometer/max5432.yaml b/Documentation/devicetree/bindings/iio/potentiometer/max5432.yaml new file mode 100644 index 000000000000..5082f919df2a --- /dev/null +++ b/Documentation/devicetree/bindings/iio/potentiometer/max5432.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/potentiometer/max5432.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim Integrated MAX5432-MAX5435 Digital Potentiometers + +maintainers: + - Martin Kaiser <martin@kaiser.cx> + +description: | + Maxim Integrated MAX5432-MAX5435 Digital Potentiometers connected via I2C + + Datasheet: + https://datasheets.maximintegrated.com/en/ds/MAX5432-MAX5435.pdf + +properties: + compatible: + enum: + - maxim,max5432 + - maxim,max5433 + - maxim,max5434 + - maxim,max5435 + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + max5434@28 { + compatible = "maxim,max5434"; + reg = <0x28>; + }; + }; |