[RFC PATCH v2] protocol: Extend wayland seat with interfaces for sensor inputs.

[Stefan Schmidt]

Hello.

On 08/22/2013 09:46 AM, Stefan Schmidt wrote:
> Treating some specific sensors as input devices. In particular
> adding support for wl_compass, wl_gyroscope and wl_accelerometer here.
>
> Using these sensor as input for apps and games. Not covering any
> background apps or services with this protocol.
>
> We have requests to start and stop sensor event receiving as well as
> events to receive the different axis values for these sensors.
>
> V2:
> o Add units to event arguments
> o Define coordinate system
> o Be more verbose on security policy in compositor and add error event

One thing I'm still missing is a way to handle more than one sensor per 
type for the future. Input devices like the wii-remote with nunchuk 
comes to mind. Having two separate accelerometers which still would be a 
the same seat but could not be aggregated.

One option we have been pondering about was adding a simple uid when 
doing the get_compass, etc calls and re-use this uid later in the motion 
events to identify the correct sensor. When the compositor adds the 
various sensors clients would get a event for each and could keep track 
on how many compass sensors there are for example and call get_compass 
accordingly if it is interested in all of them.

Its a corner case but I want this proposal to at least allow for such 
things in the future.

Anyone having a better/different idea on this?

regards
Stefan Schmidt

PS: I'm on vacation next week. Will reply to review and comments the 
week after.

> Signed-off-by: Stefan Schmidt <s.schmidt at samsung.com>
> ---
>   protocol/wayland.xml |  175
> ++++++++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 175 insertions(+)
>
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index d7bbbb9..e35413c 100644
> --- a/protocol/wayland.xml
> +++ b/protocol/wayland.xml
> @@ -1251,6 +1251,9 @@
>         <entry name="pointer" value="1" summary="The seat has pointer
> devices"/>
>         <entry name="keyboard" value="2" summary="The seat has one or more
> keyboards"/>
>         <entry name="touch" value="4" summary="The seat has touch
> devices"/>
> +      <entry name="compass" value="8" summary="The seat has compass
> devices"/>
> +      <entry name="gyroscope" value="16" summary="The seat has gyroscope
> devices"/>
> +      <entry name="accelerometer" value="32" summary="The seat has
> accelerometer devices"/>
>       </enum>
>
>       <event name="capabilities">
> @@ -1297,6 +1300,63 @@
>
>       <!-- Version 2 of additions -->
>
> +    <request name="get_compass" since="2">
> +      <description summary="return compass object">
> +        The ID provided will be initialized to the wl_compass interface
> +	for this seat.
> +
> +        This request only takes effect if the seat has the compass
> +        capability. If the seat has the capability but no object is
> +        received it could be that the compositor security policy has
> +        denied the sensor access for the client. In case of a security
> +        policy error an error event will be send.
> +      </description>
> +      <arg name="id" type="new_id" interface="wl_compass"/>
> +    </request>
> +
> +    <request name="get_gyroscope" since="2">
> +      <description summary="return gyroscope object">
> +        The ID provided will be initialized to the wl_gyroscope interface
> +	for this seat.
> +
> +        This request only takes effect if the seat has the gyroscope
> +        capability. If the seat has the capability but no object is
> +        received it could be that the compositor security policy has
> +        denied the sensor access for the client. In case of a security
> +        policy error an error event will be send.
> +      </description>
> +      <arg name="id" type="new_id" interface="wl_gyroscope"/>
> +    </request>
> +
> +    <request name="get_accelerometer" since="2">
> +      <description summary="return accelerometer object">
> +        The ID provided will be initialized to the wl_accelerometer
> interface
> +	for this seat.
> +
> +        This request only takes effect if the seat has the accelerometer
> +        capability. If the seat has the capability but no object is
> +        received it could be that the compositor security policy has
> +        denied the sensor access for the client. In case of a security
> +        policy error an error event will be send.
> +      </description>
> +      <arg name="id" type="new_id" interface="wl_accelerometer"/>
> +    </request>
> +
> +    <event name="error">
> +      <description summary="fatal error event">
> +	The error event is sent out when a fatal (non-recoverable)
> +	error has occurred.  The object_id argument is the object
> +	where the error occurred, most often in response to a request
> +	to that object.  The code identifies the error and is defined
> +	by the object interface.  As such, each interface defines its
> +	own set of error codes.  The message is an brief description
> +	of the error, for (debugging) convenience.
> +      </description>
> +      <arg name="object_id" type="object"/>
> +      <arg name="code" type="uint"/>
> +      <arg name="message" type="string"/>
> +    </event>
> +
>       <event name="name" since="2">
>         <description summary="unique identifier for this seat">
>   	In a multiseat configuration this can be used by the client to
> help
> @@ -1605,6 +1665,121 @@
>       </event>
>     </interface>
>
> +  <interface name="wl_compass" version="2">
> +    <description summary="compass sensor device">
> +      The wl_compass interface represents a compass
> +      associated with a seat.
> +    </description>
> +
> +    <request name="start">
> +      <description summary="Start receiving events">
> +	Sent to enable event receiving for the compass sensor.
> +      </description>
> +    </request>
> +
> +    <request name="stop">
> +      <description summary="Stop receiving events">
> +	Sent to disable event receiving for the compass sensor.
> +
> +	It stops event reporting to this client. Other clients might still
> +	receive events.
> +      </description>
> +    </request>
> +
> +    <event name="motion">
> +      <description summary="Motion event coming from the compass sensor">
> +	Updated sensor data available from compass
> +
> +	Measurement of the ambient magnetic field in the X, Y and Z axis.
> +
> +	Coordinate system (device in portrait mode with screen facing
> upwards):
> +	X axis goes from the left to the right side of the device
> +	Y axis goes from the bottom of the screen to the top
> +	Z axis goes from the back of the screen to the front of the screen
> +     </description>
> +      <arg name="x" type="fixed" summary="x-axis in micro Tesla (uT)"/>
> +      <arg name="y" type="fixed" summary="y-axis in micro Tesla (uT)"/>
> +      <arg name="z" type="fixed" summary="z-axis in micro Tesla (uT)"/>
> +    </event>
> +  </interface>
> +
> +  <interface name="wl_gyroscope" version="2">
> +    <description summary="gyroscope sensor device">
> +      The wl_gyroscope interface represents a gyroscope
> +      associated with a seat.
> +    </description>
> +
> +    <request name="start">
> +      <description summary="Start receiving events">
> +	Sent to enable event receiving for the gyroscope sensor.
> +      </description>
> +    </request>
> +
> +    <request name="stop">
> +      <description summary="Stop receiving events">
> +	Sent to disable event receiving for the gyroscope sensor.
> +
> +	It stops event reporting to this client. Other clients might still
> +	receive events.
> +      </description>
> +    </request>
> +
> +    <event name="motion">
> +      <description summary="Motion event coming from the gyroscope
> sensor">
> +	Updated sensor data available from gyroscope
> +
> +	Measurement of the rate of rotation around X, Y and Z axis in
> degree per second.
> +	Values are observed in positive notation in the counter-clockwise
> direction.
> +
> +	Coordinate system (device in portrait mode with screen facing
> upwards):
> +	X axis goes from the left to the right side of the device (Pitch)
> +	Y axis goes from the bottom of the screen to the top (Roll)
> +	Z axis goes from the back of the screen to the front of the screen
> (Azimuth/Yaw)
> +      </description>
> +      <arg name="x" type="fixed" summary="x-axis in degree per second"/>
> +      <arg name="y" type="fixed" summary="y-axis in degree per second"/>
> +      <arg name="z" type="fixed" summary="z-axis in degree per second"/>
> +    </event>
> +  </interface>
> +
> +  <interface name="wl_accelerometer" version="2">
> +    <description summary="accelerometer sensor device">
> +      The wl_accelerometer interface represents a accelerometer
> +      associated with a seat.
> +    </description>
> +
> +    <request name="start">
> +      <description summary="Start receiving events">
> +	Sent to enable event receiving for the accelerometer sensor.
> +      </description>
> +    </request>
> +
> +    <request name="stop">
> +      <description summary="Stop receiving events">
> +	Sent to disable event receiving for the accelerometer sensor.
> +
> +	It stops event reporting to this client. Other clients might still
> +	receive events.
> +      </description>
> +    </request>
> +
> +    <event name="motion">
> +      <description summary="Motion event coming from the accelerometer
> sensor">
> +	Updated sensor data available from accelerometer
> +
> +	Measurement of the acceleration of G on the axis in m/s^2.
> +
> +	Coordinate system (device in portrait mode with screen facing
> upwards):
> +	X axis goes from the left to the right side of the device
> +	Y axis goes from the bottom of the screen to the top
> +	Z axis goes from the back of the screen to the front of the screen
> +      </description>
> +      <arg name="x" type="fixed" summary="x-axis G in m/s^2"/>
> +      <arg name="y" type="fixed" summary="y-axis G in m/s^2"/>
> +      <arg name="z" type="fixed" summary="z-axis G in m/s^2"/>
> +    </event>
> +  </interface>
> +
>     <interface name="wl_output" version="2">
>       <description summary="compositor output region">
>         An output describes part of the compositor geometry.  The
>