From patchwork Sun Jul 24 10:17:14 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Walleij X-Patchwork-Id: 72658 Delivered-To: patch@linaro.org Received: by 10.140.29.52 with SMTP id a49csp644785qga; Sun, 24 Jul 2016 03:17:40 -0700 (PDT) X-Received: by 10.66.134.20 with SMTP id pg20mr20471464pab.98.1469355459967; Sun, 24 Jul 2016 03:17:39 -0700 (PDT) Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id af3si27303726pad.39.2016.07.24.03.17.39; Sun, 24 Jul 2016 03:17:39 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of devicetree-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; dkim=neutral (body hash did not verify) header.i=@linaro.org; spf=pass (google.com: best guess record for domain of devicetree-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=devicetree-owner@vger.kernel.org; dmarc=fail (p=NONE dis=NONE) header.from=linaro.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752184AbcGXKRi (ORCPT + 7 others); Sun, 24 Jul 2016 06:17:38 -0400 Received: from mail-lf0-f41.google.com ([209.85.215.41]:33832 "EHLO mail-lf0-f41.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752180AbcGXKRh (ORCPT ); Sun, 24 Jul 2016 06:17:37 -0400 Received: by mail-lf0-f41.google.com with SMTP id l69so111157844lfg.1 for ; Sun, 24 Jul 2016 03:17:36 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id; bh=yIgTjr/5h4Z6nyfwrEJ29JlBtlRd5EHmHCcjCLQzqLg=; b=WNvkSKsyqzww6TV1RtRjgn2P+lF3XbH6EldempCEAYmmSLMKKm+iTr6ytwaMmYsWlB y3CS04OUHusXn7oAuREmucDJeUok6Bxm3ckIfrH4YLvk476gfRVCLXFmo0/ZMJe7yJ5Z VnUnFnj0G/9yOjkYSOuf4i+q0PAfUqSh1GNAQ= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=yIgTjr/5h4Z6nyfwrEJ29JlBtlRd5EHmHCcjCLQzqLg=; b=Bj9Wr+Y4j6G1R6NVOBmIt/05RBrK6en1cnc5u/NSjz9OJp6SYvE26JwoP8wwlcJwHN rNCaNp133g65pV7JDWXlhfW9b82JP40Fi5FvJafnja1D2qQJD7m9QXS5aiGMlTpaE3Ay q7aEpwcNl7IqT3D09v7j0ovsY1an+acc2FzaaSIapopJb9gFEsVSp2gCZWBFfGKPh62J leHoLYoPy5f4mWDPF2A2FR8D/tn54FJvubbsBeC0VWdBph6/oubnRLe2R8zjEi+Xjmv5 TMEAhzCxQnKb6lkcgtDRulvyvffwoZi9fQDuFAfWTDtFTp9K+HNAkcXkwP1GkZGva/aZ 067g== X-Gm-Message-State: AEkoouv37xbGn9hveS/fMFAfoBhx8BnJtcLN/5ZHd7I8eG7Xwtg+L42aKgetEMvAjC0yvaq3 X-Received: by 10.25.162.138 with SMTP id l132mr5135804lfe.137.1469355455134; Sun, 24 Jul 2016 03:17:35 -0700 (PDT) Received: from localhost.localdomain.localdomain (c-cc7c71d5.014-348-6c756e10.cust.bredbandsbolaget.se. [213.113.124.204]) by smtp.gmail.com with ESMTPSA id g72sm4584272lji.43.2016.07.24.03.17.32 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sun, 24 Jul 2016 03:17:33 -0700 (PDT) From: Linus Walleij To: Jonathan Cameron , linux-iio@vger.kernel.org Cc: Linus Walleij , Gregor Boirie , Sebastian Reichel , Samu Onkalo , devicetree@vger.kernel.org Subject: [PATCH] iio: document bindings for mounting matrixes Date: Sun, 24 Jul 2016 12:17:14 +0200 Message-Id: <1469355434-17043-1-git-send-email-linus.walleij@linaro.org> X-Mailer: git-send-email 2.7.4 Sender: devicetree-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: devicetree@vger.kernel.org The mounting matrix for sensors was introduced in commit dfc57732ad38 ("iio:core: mounting matrix support") However the device tree bindings are very terse and since this is a widely applicable property, we need a proper binding for it that the other bindings can reference. This will also be useful for other operating systems and sensor engineering at large. I think all 3D sensors should support it, the current situation is probably that the mounting information is confined in magic userspace components rather than using the mounting matrix, which is not good for portability and reuse. Cc: Gregor Boirie Cc: Sebastian Reichel Cc: Samu Onkalo Cc: devicetree@vger.kernel.org Signed-off-by: Linus Walleij --- Please help out to get this right, I think this could be confusing to users unless documented properly. I think the doc has some rough edges since I'm not the smartest in physics nor english at all times. --- .../devicetree/bindings/iio/mount-matrix.txt | 104 +++++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 Documentation/devicetree/bindings/iio/mount-matrix.txt -- 2.7.4 -- To unsubscribe from this list: send the line "unsubscribe devicetree" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Acked-by: Rob Herring diff --git a/Documentation/devicetree/bindings/iio/mount-matrix.txt b/Documentation/devicetree/bindings/iio/mount-matrix.txt new file mode 100644 index 000000000000..3e72c92c5689 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt @@ -0,0 +1,104 @@ +Mounting matrix + +The mounting matrix is a device tree property used to orient any IIO device +that produce three-dimensional data. + +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 point of reference. + +For example a device with some kind of screen, where the user is supposed to +interact with the environment using a 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. + +The axes may also be flipped: for a screen you probably want (x) coordinates to +go from negative on the left to positive on the right and (z) depth to be +negative under the screen and positive in front of it, toward the face of the +user. + +Apart from flipping, a sensor can of course also be mounted in any angle along +the axes relative to the point of reference. This means that the axes may be +not only flipped, but tilted. + +Examples for some three-dimensional sensor types: + +- Accelerometers have their frame of reference is toward the center of gravity, + usually to the core of the planet, and users would likely expect a value of + 9.81N upwards along the (z) axis when the device is held with its screen + perpendicular to the planets surface and 0 on the other axes. A reading of + the (x,y,z) values will give the orientation of the device relative to the + center of the planet, i.e. relative to its surface at this point. Up and down + relative to the point of reference can thus be determined. + +- Magnetometers (compasses) have their frame of reference relative to the + geomagnetic field. In a mounting matrix for a magnetometer sensor the main + hardware orientation 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. + +- Gyroscopes detects the movement relative the device itself, and has no other + frame of reference than the mounting chassis itself. The angular momentum 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 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. + +So unless the sensor is ideally mounted, we need a means to indicate the +relative orientation of any given sensor of this type. + +To achieve this, use the device tree property "mount-matrix" for the sensor. +This supplies a 3x3 transformation 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 coordinates in three-dimensional +space, relative to some relevant point of reference. + +The mounting matrix has the layout: + + (x0, y0, z0) + (x1, y1, z1) + (x2, y2, z3) + +And it is represented as an array of strings containing the real values for +producing the transformation matrix. The real values use a decimal point and +a minus (-) to indicate a negative value. + +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"; + +Flipped X axis (negative values means positive): + +mount-matrix = "-1", "0", "0", + "0", "1", "0", + "0", "0", "1"; + +X and Y flipped (X values are for Y and Y values are for X): + +mount-matrix = "0", "1", "0", + "1", "0", "0", + "0", "0", "1"; + +Complex angular mounting with X and Z in a certain tilted orienation and +Y flipped: + +mount-matrix = "-0.984807753012208", /* x0 */ + "0", /* y0 */ + "-0.173648177666930", /* z0 */ + "0", /* x1 */ + "-1", /* y1 */ + "0", /* z1 */ + "-0.173648177666930", /* x2 */ + "0", /* y2 */ + "0.984807753012208"; /* z2 */