Question about ABS_DISTANCE's intended usage.

Question about ABS_DISTANCE's intended usage.

[Charles Mooney]

Hello all,

I'm currently working with a touchpad vendor with a new device that
supports a limited form of hover detection.  Their sensor is able to
detect the presence or absence of a finger/hand/palm hovering over the
sensor without touching it, but is unable to report any more details
about it.  This is a more limited form of hover detection than some
devices which attach a hover state to each finger they see, and can
even report x/y coordinates to hovering finger.

Instead of using ABS_MT_DISTANCE, it appears that the correct event to
use would be ABS_DISTANCE, since the value is not tied to a specific
finger.  I would like to check with you all about how this value is
intended to be used, because it's not quite as obvious to me as I
first thought.

We need to handle three basic states:
  1. At least one finger is touching the pad.
  2. Something is hovering, but nothing is actually touching.
  3. Nothing is touching the pad and nothing is detected hovering over it either

It's seems clear to me that an ABS_DISTANCE of zero should indicate
state #1 and that any other legal positive value should indicate state
#2, but I'm less clear on what the best way to handle state #3 is.
Currently, I think the best strategy would be to use a value of
ABS_DISTANCE = -1 to indicate that there are no fingers seen (hovering
or otherwise), does that make sense?

If not this, how else would you suggest that this ought to be done?

Thank you,
Charlie

Re: Question about ABS_DISTANCE's intended usage.

[Dmitry Torokhov]

On Tue, Feb 09, 2016 at 01:56:05PM -0800, Charles Mooney wrote:
> Hello all,
> 
> I'm currently working with a touchpad vendor with a new device that
> supports a limited form of hover detection.  Their sensor is able to
> detect the presence or absence of a finger/hand/palm hovering over the
> sensor without touching it, but is unable to report any more details
> about it.  This is a more limited form of hover detection than some
> devices which attach a hover state to each finger they see, and can
> even report x/y coordinates to hovering finger.
> 
> Instead of using ABS_MT_DISTANCE, it appears that the correct event to
> use would be ABS_DISTANCE, since the value is not tied to a specific
> finger.  I would like to check with you all about how this value is
> intended to be used, because it's not quite as obvious to me as I
> first thought.
> 
> We need to handle three basic states:
>   1. At least one finger is touching the pad.
>   2. Something is hovering, but nothing is actually touching.
>   3. Nothing is touching the pad and nothing is detected hovering over it either
> 
> It's seems clear to me that an ABS_DISTANCE of zero should indicate
> state #1 and that any other legal positive value should indicate state
> #2, but I'm less clear on what the best way to handle state #3 is.
> Currently, I think the best strategy would be to use a value of
> ABS_DISTANCE = -1 to indicate that there are no fingers seen (hovering
> or otherwise), does that make sense?
> 
> If not this, how else would you suggest that this ought to be done?

As we discussed in person, I believe that reporting an "out of bounds"
value for ABS_DISTANCE when we have to use single-touch mode and thus do
not have a good way to invalidate a contact, is the easiest option.
Alternative would be to invent another SYN event, which I'd rather not.

So for devices that support hovering but can not report individual
hovering contacts we should declare 0..N as ABS_DISTANCE range and report
following values:

 - 0 when a finger is actually touching
 - 1..N for hovering fingers
 - return X < 0 or X > N when no fingers are detected at all; in
   practice I think we should simply report -1 in this case.

Benjamin, Peter, Henrik, any concerns?

Thanks.

-- 
Dmitry

Re: Question about ABS_DISTANCE's intended usage.

[Peter Hutterer]

On Thu, Feb 18, 2016 at 10:19:30AM -0800, Dmitry Torokhov wrote:
> On Tue, Feb 09, 2016 at 01:56:05PM -0800, Charles Mooney wrote:
> > Hello all,
> > 
> > I'm currently working with a touchpad vendor with a new device that
> > supports a limited form of hover detection.  Their sensor is able to
> > detect the presence or absence of a finger/hand/palm hovering over the
> > sensor without touching it, but is unable to report any more details
> > about it.  This is a more limited form of hover detection than some
> > devices which attach a hover state to each finger they see, and can
> > even report x/y coordinates to hovering finger.
> > 
> > Instead of using ABS_MT_DISTANCE, it appears that the correct event to
> > use would be ABS_DISTANCE, since the value is not tied to a specific
> > finger.  I would like to check with you all about how this value is
> > intended to be used, because it's not quite as obvious to me as I
> > first thought.
> > 
> > We need to handle three basic states:
> >   1. At least one finger is touching the pad.
> >   2. Something is hovering, but nothing is actually touching.
> >   3. Nothing is touching the pad and nothing is detected hovering over it either
> > 
> > It's seems clear to me that an ABS_DISTANCE of zero should indicate
> > state #1 and that any other legal positive value should indicate state
> > #2, but I'm less clear on what the best way to handle state #3 is.
> > Currently, I think the best strategy would be to use a value of
> > ABS_DISTANCE = -1 to indicate that there are no fingers seen (hovering
> > or otherwise), does that make sense?
> > 
> > If not this, how else would you suggest that this ought to be done?
> 
> As we discussed in person, I believe that reporting an "out of bounds"
> value for ABS_DISTANCE when we have to use single-touch mode and thus do
> not have a good way to invalidate a contact, is the easiest option.
> Alternative would be to invent another SYN event, which I'd rather not.
> 
> So for devices that support hovering but can not report individual
> hovering contacts we should declare 0..N as ABS_DISTANCE range and report
> following values:
> 
>  - 0 when a finger is actually touching
>  - 1..N for hovering fingers
>  - return X < 0 or X > N when no fingers are detected at all; in
>    practice I think we should simply report -1 in this case.
> 
> Benjamin, Peter, Henrik, any concerns?

on the touchpads that support hovering we're already using BTN_TOOL_FINGER
together with ABS_DISTANCE, without needing out-of-range reports.
BTN_TOUCH is the signal when a finger is physically touching (or ABS_PRESSURE
if it exists and clients care about it).

So the sequence Charles should send is:

3) <nothing> :)
2)
    EV_ABS ABS_DISTANCE <d> # for d > 0
    EV_KEY BTN_TOOL_FINGER 1
    EV_SYN SYN_REPORT 0
1)
    EV_ABS ABS_DISTANCE 0
    EV_ABS ABS_X <x>
    EV_ABS ABS_Y <y>
    ...
    EV_KEY BTN_TOUCH 1
    EV_SYN SYN_REPORT 0
2) 
    EV_ABS ABS_DISTANCE <d> # for d > 0
    EV_KEY BTN_TOUCH 0
    EV_SYN SYN_REPORT 0
3)
    EV_KEY BTN_TOOL_FINGER 0
    EV_SYN SYN_REPORT 0

This should work with at least libinput, though I have to check what happens
when you don't send x/y on the first event. I think this would need a patch
in libinput, but that's doable. And it's the same sequence we also use for
e.g. pen tools that support hovering as well.

Cheers,
   Peter

Re: Question about ABS_DISTANCE's intended usage.

[Charles Mooney]

On Sun, Feb 21, 2016 at 2:04 PM Peter Hutterer <peter.hutterer@who-t.net> wrote:
>
> On Thu, Feb 18, 2016 at 10:19:30AM -0800, Dmitry Torokhov wrote:
> > On Tue, Feb 09, 2016 at 01:56:05PM -0800, Charles Mooney wrote:
> > > Hello all,
> > >
> > > I'm currently working with a touchpad vendor with a new device that
> > > supports a limited form of hover detection.  Their sensor is able to
> > > detect the presence or absence of a finger/hand/palm hovering over the
> > > sensor without touching it, but is unable to report any more details
> > > about it.  This is a more limited form of hover detection than some
> > > devices which attach a hover state to each finger they see, and can
> > > even report x/y coordinates to hovering finger.
> > >
> > > Instead of using ABS_MT_DISTANCE, it appears that the correct event to
> > > use would be ABS_DISTANCE, since the value is not tied to a specific
> > > finger.  I would like to check with you all about how this value is
> > > intended to be used, because it's not quite as obvious to me as I
> > > first thought.
> > >
> > > We need to handle three basic states:
> > >   1. At least one finger is touching the pad.
> > >   2. Something is hovering, but nothing is actually touching.
> > >   3. Nothing is touching the pad and nothing is detected hovering over it either
> > >
> > > It's seems clear to me that an ABS_DISTANCE of zero should indicate
> > > state #1 and that any other legal positive value should indicate state
> > > #2, but I'm less clear on what the best way to handle state #3 is.
> > > Currently, I think the best strategy would be to use a value of
> > > ABS_DISTANCE = -1 to indicate that there are no fingers seen (hovering
> > > or otherwise), does that make sense?
> > >
> > > If not this, how else would you suggest that this ought to be done?
> >
> > As we discussed in person, I believe that reporting an "out of bounds"
> > value for ABS_DISTANCE when we have to use single-touch mode and thus do
> > not have a good way to invalidate a contact, is the easiest option.
> > Alternative would be to invent another SYN event, which I'd rather not.
> >
> > So for devices that support hovering but can not report individual
> > hovering contacts we should declare 0..N as ABS_DISTANCE range and report
> > following values:
> >
> >  - 0 when a finger is actually touching
> >  - 1..N for hovering fingers
> >  - return X < 0 or X > N when no fingers are detected at all; in
> >    practice I think we should simply report -1 in this case.
> >
> > Benjamin, Peter, Henrik, any concerns?
>
> on the touchpads that support hovering we're already using BTN_TOOL_FINGER
> together with ABS_DISTANCE, without needing out-of-range reports.
> BTN_TOUCH is the signal when a finger is physically touching (or ABS_PRESSURE
> if it exists and clients care about it).
>
> So the sequence Charles should send is:
>
> 3) <nothing> :)
> 2)
>     EV_ABS ABS_DISTANCE <d> # for d > 0
>     EV_KEY BTN_TOOL_FINGER 1
>     EV_SYN SYN_REPORT 0
> 1)
>     EV_ABS ABS_DISTANCE 0
>     EV_ABS ABS_X <x>
>     EV_ABS ABS_Y <y>
>     ...
>     EV_KEY BTN_TOUCH 1
>     EV_SYN SYN_REPORT 0
> 2)
>     EV_ABS ABS_DISTANCE <d> # for d > 0
>     EV_KEY BTN_TOUCH 0
>     EV_SYN SYN_REPORT 0
> 3)
>     EV_KEY BTN_TOOL_FINGER 0
>     EV_SYN SYN_REPORT 0
>
> This should work with at least libinput, though I have to check what happens
> when you don't send x/y on the first event. I think this would need a patch
> in libinput, but that's doable. And it's the same sequence we also use for
> e.g. pen tools that support hovering as well.
>
> Cheers,
>    Peter

Hi Peter,

It looks like you're suggesting to use "BTN_TOOL_FINGER" as a signal
as to weather or not the value in "ABS_DISTANCE" is valid or not.

1. No finger detected anywhere:
    BTN_TOOL_FINGER = 0
    ABS_DISTANCE = n/a
2. Finger seen hovering but not touching:
    BTN_TOOL_FINGER = 1
    ABS_DISTANCE > 0
2. Finger touching:
    BTN_TOOL_FINGER = 1
    ABS_DISTANCE = 0

Am I understanding that correctly?

Re: Question about ABS_DISTANCE's intended usage.

[Peter Hutterer]

On Mon, Feb 22, 2016 at 08:35:31AM -0800, Charles Mooney wrote:
> On Sun, Feb 21, 2016 at 2:04 PM Peter Hutterer <peter.hutterer@who-t.net> wrote:
> >
> > On Thu, Feb 18, 2016 at 10:19:30AM -0800, Dmitry Torokhov wrote:
> > > On Tue, Feb 09, 2016 at 01:56:05PM -0800, Charles Mooney wrote:
> > > > Hello all,
> > > >
> > > > I'm currently working with a touchpad vendor with a new device that
> > > > supports a limited form of hover detection.  Their sensor is able to
> > > > detect the presence or absence of a finger/hand/palm hovering over the
> > > > sensor without touching it, but is unable to report any more details
> > > > about it.  This is a more limited form of hover detection than some
> > > > devices which attach a hover state to each finger they see, and can
> > > > even report x/y coordinates to hovering finger.
> > > >
> > > > Instead of using ABS_MT_DISTANCE, it appears that the correct event to
> > > > use would be ABS_DISTANCE, since the value is not tied to a specific
> > > > finger.  I would like to check with you all about how this value is
> > > > intended to be used, because it's not quite as obvious to me as I
> > > > first thought.
> > > >
> > > > We need to handle three basic states:
> > > >   1. At least one finger is touching the pad.
> > > >   2. Something is hovering, but nothing is actually touching.
> > > >   3. Nothing is touching the pad and nothing is detected hovering over it either
> > > >
> > > > It's seems clear to me that an ABS_DISTANCE of zero should indicate
> > > > state #1 and that any other legal positive value should indicate state
> > > > #2, but I'm less clear on what the best way to handle state #3 is.
> > > > Currently, I think the best strategy would be to use a value of
> > > > ABS_DISTANCE = -1 to indicate that there are no fingers seen (hovering
> > > > or otherwise), does that make sense?
> > > >
> > > > If not this, how else would you suggest that this ought to be done?
> > >
> > > As we discussed in person, I believe that reporting an "out of bounds"
> > > value for ABS_DISTANCE when we have to use single-touch mode and thus do
> > > not have a good way to invalidate a contact, is the easiest option.
> > > Alternative would be to invent another SYN event, which I'd rather not.
> > >
> > > So for devices that support hovering but can not report individual
> > > hovering contacts we should declare 0..N as ABS_DISTANCE range and report
> > > following values:
> > >
> > >  - 0 when a finger is actually touching
> > >  - 1..N for hovering fingers
> > >  - return X < 0 or X > N when no fingers are detected at all; in
> > >    practice I think we should simply report -1 in this case.
> > >
> > > Benjamin, Peter, Henrik, any concerns?
> >
> > on the touchpads that support hovering we're already using BTN_TOOL_FINGER
> > together with ABS_DISTANCE, without needing out-of-range reports.
> > BTN_TOUCH is the signal when a finger is physically touching (or ABS_PRESSURE
> > if it exists and clients care about it).
> >
> > So the sequence Charles should send is:
> >
> > 3) <nothing> :)
> > 2)
> >     EV_ABS ABS_DISTANCE <d> # for d > 0
> >     EV_KEY BTN_TOOL_FINGER 1
> >     EV_SYN SYN_REPORT 0
> > 1)
> >     EV_ABS ABS_DISTANCE 0
> >     EV_ABS ABS_X <x>
> >     EV_ABS ABS_Y <y>
> >     ...
> >     EV_KEY BTN_TOUCH 1
> >     EV_SYN SYN_REPORT 0
> > 2)
> >     EV_ABS ABS_DISTANCE <d> # for d > 0
> >     EV_KEY BTN_TOUCH 0
> >     EV_SYN SYN_REPORT 0
> > 3)
> >     EV_KEY BTN_TOOL_FINGER 0
> >     EV_SYN SYN_REPORT 0
> >
> > This should work with at least libinput, though I have to check what happens
> > when you don't send x/y on the first event. I think this would need a patch
> > in libinput, but that's doable. And it's the same sequence we also use for
> > e.g. pen tools that support hovering as well.
> >
> > Cheers,
> >    Peter
> 
> Hi Peter,
> 
> It looks like you're suggesting to use "BTN_TOOL_FINGER" as a signal
> as to weather or not the value in "ABS_DISTANCE" is valid or not.
> 
> 1. No finger detected anywhere:
>     BTN_TOOL_FINGER = 0
>     ABS_DISTANCE = n/a
> 2. Finger seen hovering but not touching:
>     BTN_TOOL_FINGER = 1
>     ABS_DISTANCE > 0
> 2. Finger touching:
>     BTN_TOOL_FINGER = 1
>     ABS_DISTANCE = 0

you should set BTN_TOUCH here. This can be done based on some magic pressure
threshold if you have pressure, otherwise just unconditionally set it
whenever distance is 0.

> 
> Am I understanding that correctly?

yes, but IMO better to think it this way: BTN_TOOL_FINGER signals whether a
finger is detected by the device. everything else is just axis information
if and when it becomes available.
likewise, BTN_TOUCH signals whether the current tool (could be something
other than finger) logically touches the surface.

Cheers,
   Peter

Re: Question about ABS_DISTANCE's intended usage.

[Dmitry Torokhov]

On Tue, Feb 23, 2016 at 08:04:32AM +1000, Peter Hutterer wrote:
> On Mon, Feb 22, 2016 at 08:35:31AM -0800, Charles Mooney wrote:
> > On Sun, Feb 21, 2016 at 2:04 PM Peter Hutterer <peter.hutterer@who-t.net> wrote:
> > >
> > > On Thu, Feb 18, 2016 at 10:19:30AM -0800, Dmitry Torokhov wrote:
> > > > On Tue, Feb 09, 2016 at 01:56:05PM -0800, Charles Mooney wrote:
> > > > > Hello all,
> > > > >
> > > > > I'm currently working with a touchpad vendor with a new device that
> > > > > supports a limited form of hover detection.  Their sensor is able to
> > > > > detect the presence or absence of a finger/hand/palm hovering over the
> > > > > sensor without touching it, but is unable to report any more details
> > > > > about it.  This is a more limited form of hover detection than some
> > > > > devices which attach a hover state to each finger they see, and can
> > > > > even report x/y coordinates to hovering finger.
> > > > >
> > > > > Instead of using ABS_MT_DISTANCE, it appears that the correct event to
> > > > > use would be ABS_DISTANCE, since the value is not tied to a specific
> > > > > finger.  I would like to check with you all about how this value is
> > > > > intended to be used, because it's not quite as obvious to me as I
> > > > > first thought.
> > > > >
> > > > > We need to handle three basic states:
> > > > >   1. At least one finger is touching the pad.
> > > > >   2. Something is hovering, but nothing is actually touching.
> > > > >   3. Nothing is touching the pad and nothing is detected hovering over it either
> > > > >
> > > > > It's seems clear to me that an ABS_DISTANCE of zero should indicate
> > > > > state #1 and that any other legal positive value should indicate state
> > > > > #2, but I'm less clear on what the best way to handle state #3 is.
> > > > > Currently, I think the best strategy would be to use a value of
> > > > > ABS_DISTANCE = -1 to indicate that there are no fingers seen (hovering
> > > > > or otherwise), does that make sense?
> > > > >
> > > > > If not this, how else would you suggest that this ought to be done?
> > > >
> > > > As we discussed in person, I believe that reporting an "out of bounds"
> > > > value for ABS_DISTANCE when we have to use single-touch mode and thus do
> > > > not have a good way to invalidate a contact, is the easiest option.
> > > > Alternative would be to invent another SYN event, which I'd rather not.
> > > >
> > > > So for devices that support hovering but can not report individual
> > > > hovering contacts we should declare 0..N as ABS_DISTANCE range and report
> > > > following values:
> > > >
> > > >  - 0 when a finger is actually touching
> > > >  - 1..N for hovering fingers
> > > >  - return X < 0 or X > N when no fingers are detected at all; in
> > > >    practice I think we should simply report -1 in this case.
> > > >
> > > > Benjamin, Peter, Henrik, any concerns?
> > >
> > > on the touchpads that support hovering we're already using BTN_TOOL_FINGER
> > > together with ABS_DISTANCE, without needing out-of-range reports.
> > > BTN_TOUCH is the signal when a finger is physically touching (or ABS_PRESSURE
> > > if it exists and clients care about it).
> > >
> > > So the sequence Charles should send is:
> > >
> > > 3) <nothing> :)
> > > 2)
> > >     EV_ABS ABS_DISTANCE <d> # for d > 0
> > >     EV_KEY BTN_TOOL_FINGER 1
> > >     EV_SYN SYN_REPORT 0
> > > 1)
> > >     EV_ABS ABS_DISTANCE 0
> > >     EV_ABS ABS_X <x>
> > >     EV_ABS ABS_Y <y>
> > >     ...
> > >     EV_KEY BTN_TOUCH 1
> > >     EV_SYN SYN_REPORT 0
> > > 2)
> > >     EV_ABS ABS_DISTANCE <d> # for d > 0
> > >     EV_KEY BTN_TOUCH 0
> > >     EV_SYN SYN_REPORT 0
> > > 3)
> > >     EV_KEY BTN_TOOL_FINGER 0
> > >     EV_SYN SYN_REPORT 0
> > >
> > > This should work with at least libinput, though I have to check what happens
> > > when you don't send x/y on the first event. I think this would need a patch
> > > in libinput, but that's doable. And it's the same sequence we also use for
> > > e.g. pen tools that support hovering as well.
> > >
> > > Cheers,
> > >    Peter
> > 
> > Hi Peter,
> > 
> > It looks like you're suggesting to use "BTN_TOOL_FINGER" as a signal
> > as to weather or not the value in "ABS_DISTANCE" is valid or not.
> > 
> > 1. No finger detected anywhere:
> >     BTN_TOOL_FINGER = 0
> >     ABS_DISTANCE = n/a
> > 2. Finger seen hovering but not touching:
> >     BTN_TOOL_FINGER = 1
> >     ABS_DISTANCE > 0
> > 2. Finger touching:
> >     BTN_TOOL_FINGER = 1
> >     ABS_DISTANCE = 0
> 
> you should set BTN_TOUCH here. This can be done based on some magic pressure
> threshold if you have pressure, otherwise just unconditionally set it
> whenever distance is 0.
> 
> > 
> > Am I understanding that correctly?
> 
> yes, but IMO better to think it this way: BTN_TOOL_FINGER signals whether a
> finger is detected by the device. everything else is just axis information
> if and when it becomes available.
> likewise, BTN_TOUCH signals whether the current tool (could be something
> other than finger) logically touches the surface.

I wonder if this will not confuse clients that do not pay attention to
ABS_DISTANCE though... I take it that libinput and x synaptics drivers
won't be confused, mousedev in kernel relies on BTN_TOUCH, what about
others?

Thanks.

-- 
Dmitry

Re: Question about ABS_DISTANCE's intended usage.

[Peter Hutterer]

On Tue, Feb 23, 2016 at 02:02:45PM -0800, Dmitry Torokhov wrote:
> On Tue, Feb 23, 2016 at 08:04:32AM +1000, Peter Hutterer wrote:
> > On Mon, Feb 22, 2016 at 08:35:31AM -0800, Charles Mooney wrote:
> > > On Sun, Feb 21, 2016 at 2:04 PM Peter Hutterer <peter.hutterer@who-t.net> wrote:
> > > >
> > > > On Thu, Feb 18, 2016 at 10:19:30AM -0800, Dmitry Torokhov wrote:
> > > > > On Tue, Feb 09, 2016 at 01:56:05PM -0800, Charles Mooney wrote:
> > > > > > Hello all,
> > > > > >
> > > > > > I'm currently working with a touchpad vendor with a new device that
> > > > > > supports a limited form of hover detection.  Their sensor is able to
> > > > > > detect the presence or absence of a finger/hand/palm hovering over the
> > > > > > sensor without touching it, but is unable to report any more details
> > > > > > about it.  This is a more limited form of hover detection than some
> > > > > > devices which attach a hover state to each finger they see, and can
> > > > > > even report x/y coordinates to hovering finger.
> > > > > >
> > > > > > Instead of using ABS_MT_DISTANCE, it appears that the correct event to
> > > > > > use would be ABS_DISTANCE, since the value is not tied to a specific
> > > > > > finger.  I would like to check with you all about how this value is
> > > > > > intended to be used, because it's not quite as obvious to me as I
> > > > > > first thought.
> > > > > >
> > > > > > We need to handle three basic states:
> > > > > >   1. At least one finger is touching the pad.
> > > > > >   2. Something is hovering, but nothing is actually touching.
> > > > > >   3. Nothing is touching the pad and nothing is detected hovering over it either
> > > > > >
> > > > > > It's seems clear to me that an ABS_DISTANCE of zero should indicate
> > > > > > state #1 and that any other legal positive value should indicate state
> > > > > > #2, but I'm less clear on what the best way to handle state #3 is.
> > > > > > Currently, I think the best strategy would be to use a value of
> > > > > > ABS_DISTANCE = -1 to indicate that there are no fingers seen (hovering
> > > > > > or otherwise), does that make sense?
> > > > > >
> > > > > > If not this, how else would you suggest that this ought to be done?
> > > > >
> > > > > As we discussed in person, I believe that reporting an "out of bounds"
> > > > > value for ABS_DISTANCE when we have to use single-touch mode and thus do
> > > > > not have a good way to invalidate a contact, is the easiest option.
> > > > > Alternative would be to invent another SYN event, which I'd rather not.
> > > > >
> > > > > So for devices that support hovering but can not report individual
> > > > > hovering contacts we should declare 0..N as ABS_DISTANCE range and report
> > > > > following values:
> > > > >
> > > > >  - 0 when a finger is actually touching
> > > > >  - 1..N for hovering fingers
> > > > >  - return X < 0 or X > N when no fingers are detected at all; in
> > > > >    practice I think we should simply report -1 in this case.
> > > > >
> > > > > Benjamin, Peter, Henrik, any concerns?
> > > >
> > > > on the touchpads that support hovering we're already using BTN_TOOL_FINGER
> > > > together with ABS_DISTANCE, without needing out-of-range reports.
> > > > BTN_TOUCH is the signal when a finger is physically touching (or ABS_PRESSURE
> > > > if it exists and clients care about it).
> > > >
> > > > So the sequence Charles should send is:
> > > >
> > > > 3) <nothing> :)
> > > > 2)
> > > >     EV_ABS ABS_DISTANCE <d> # for d > 0
> > > >     EV_KEY BTN_TOOL_FINGER 1
> > > >     EV_SYN SYN_REPORT 0
> > > > 1)
> > > >     EV_ABS ABS_DISTANCE 0
> > > >     EV_ABS ABS_X <x>
> > > >     EV_ABS ABS_Y <y>
> > > >     ...
> > > >     EV_KEY BTN_TOUCH 1
> > > >     EV_SYN SYN_REPORT 0
> > > > 2)
> > > >     EV_ABS ABS_DISTANCE <d> # for d > 0
> > > >     EV_KEY BTN_TOUCH 0
> > > >     EV_SYN SYN_REPORT 0
> > > > 3)
> > > >     EV_KEY BTN_TOOL_FINGER 0
> > > >     EV_SYN SYN_REPORT 0
> > > >
> > > > This should work with at least libinput, though I have to check what happens
> > > > when you don't send x/y on the first event. I think this would need a patch
> > > > in libinput, but that's doable. And it's the same sequence we also use for
> > > > e.g. pen tools that support hovering as well.
> > > >
> > > > Cheers,
> > > >    Peter
> > > 
> > > Hi Peter,
> > > 
> > > It looks like you're suggesting to use "BTN_TOOL_FINGER" as a signal
> > > as to weather or not the value in "ABS_DISTANCE" is valid or not.
> > > 
> > > 1. No finger detected anywhere:
> > >     BTN_TOOL_FINGER = 0
> > >     ABS_DISTANCE = n/a
> > > 2. Finger seen hovering but not touching:
> > >     BTN_TOOL_FINGER = 1
> > >     ABS_DISTANCE > 0
> > > 2. Finger touching:
> > >     BTN_TOOL_FINGER = 1
> > >     ABS_DISTANCE = 0
> > 
> > you should set BTN_TOUCH here. This can be done based on some magic pressure
> > threshold if you have pressure, otherwise just unconditionally set it
> > whenever distance is 0.
> > 
> > > 
> > > Am I understanding that correctly?
> > 
> > yes, but IMO better to think it this way: BTN_TOOL_FINGER signals whether a
> > finger is detected by the device. everything else is just axis information
> > if and when it becomes available.
> > likewise, BTN_TOUCH signals whether the current tool (could be something
> > other than finger) logically touches the surface.
> 
> I wonder if this will not confuse clients that do not pay attention to
> ABS_DISTANCE though... I take it that libinput and x synaptics drivers
> won't be confused, mousedev in kernel relies on BTN_TOUCH, what about
> others?

if they get confused, they'd already be confused by a set of current
devices. This isn't new behaviour, we've been doing this for quite a while.
and as I said above, it matches the behaviour we use for BTN_TOOL_PEN, it's
IMO hard to justify that the behaviour should be different between the two
tools.

Cheers,
   Peter

Re: Question about ABS_DISTANCE's intended usage.

[Henrik Rydberg]

Hi Dmitry, Charles, Peter,

> I wonder if this will not confuse clients that do not pay attention to
> ABS_DISTANCE though... I take it that libinput and x synaptics drivers
> won't be confused, mousedev in kernel relies on BTN_TOUCH, what about
> others?

It looks quite ok with BTN_TOUCH added. So for n the number of detected fingers
and d the collective distance to the surface:

BTN_DISTANCE = d
BTN_TOUCH = (d == 0)
BTN_TOOL_FINGER = (n == 1)
BTN_TOOL_DOUBLETAP = (n == 2)
BTN_TOOL_TRIPLE...

This will work for:

1. The simplest touchscreen driver which only looks at BTN_TOUCH.
2. Touchpad drivers that distinguish between fingers present (BTN_TOOL_FINGER)
and fingers touching (BTN_TOUCH).
3. Drivers that already understand BTN_DISTANCE, as per Peter's description.

Charles' three states are then encoded as

#1 (d = 0, n > 0)
#2 (d > 0, n > 0)
#3 (d = ?, n = 0)

I don't recall any kernel or userland driver working any differently either.

Henrik

Re: Question about ABS_DISTANCE's intended usage.

[Dmitry Torokhov]

On Wed, Feb 24, 2016 at 08:39:15AM +1000, Peter Hutterer wrote:
> On Tue, Feb 23, 2016 at 02:02:45PM -0800, Dmitry Torokhov wrote:
> > On Tue, Feb 23, 2016 at 08:04:32AM +1000, Peter Hutterer wrote:
> > > On Mon, Feb 22, 2016 at 08:35:31AM -0800, Charles Mooney wrote:
> > > > On Sun, Feb 21, 2016 at 2:04 PM Peter Hutterer <peter.hutterer@who-t.net> wrote:
> > > > >
> > > > > On Thu, Feb 18, 2016 at 10:19:30AM -0800, Dmitry Torokhov wrote:
> > > > > > On Tue, Feb 09, 2016 at 01:56:05PM -0800, Charles Mooney wrote:
> > > > > > > Hello all,
> > > > > > >
> > > > > > > I'm currently working with a touchpad vendor with a new device that
> > > > > > > supports a limited form of hover detection.  Their sensor is able to
> > > > > > > detect the presence or absence of a finger/hand/palm hovering over the
> > > > > > > sensor without touching it, but is unable to report any more details
> > > > > > > about it.  This is a more limited form of hover detection than some
> > > > > > > devices which attach a hover state to each finger they see, and can
> > > > > > > even report x/y coordinates to hovering finger.
> > > > > > >
> > > > > > > Instead of using ABS_MT_DISTANCE, it appears that the correct event to
> > > > > > > use would be ABS_DISTANCE, since the value is not tied to a specific
> > > > > > > finger.  I would like to check with you all about how this value is
> > > > > > > intended to be used, because it's not quite as obvious to me as I
> > > > > > > first thought.
> > > > > > >
> > > > > > > We need to handle three basic states:
> > > > > > >   1. At least one finger is touching the pad.
> > > > > > >   2. Something is hovering, but nothing is actually touching.
> > > > > > >   3. Nothing is touching the pad and nothing is detected hovering over it either
> > > > > > >
> > > > > > > It's seems clear to me that an ABS_DISTANCE of zero should indicate
> > > > > > > state #1 and that any other legal positive value should indicate state
> > > > > > > #2, but I'm less clear on what the best way to handle state #3 is.
> > > > > > > Currently, I think the best strategy would be to use a value of
> > > > > > > ABS_DISTANCE = -1 to indicate that there are no fingers seen (hovering
> > > > > > > or otherwise), does that make sense?
> > > > > > >
> > > > > > > If not this, how else would you suggest that this ought to be done?
> > > > > >
> > > > > > As we discussed in person, I believe that reporting an "out of bounds"
> > > > > > value for ABS_DISTANCE when we have to use single-touch mode and thus do
> > > > > > not have a good way to invalidate a contact, is the easiest option.
> > > > > > Alternative would be to invent another SYN event, which I'd rather not.
> > > > > >
> > > > > > So for devices that support hovering but can not report individual
> > > > > > hovering contacts we should declare 0..N as ABS_DISTANCE range and report
> > > > > > following values:
> > > > > >
> > > > > >  - 0 when a finger is actually touching
> > > > > >  - 1..N for hovering fingers
> > > > > >  - return X < 0 or X > N when no fingers are detected at all; in
> > > > > >    practice I think we should simply report -1 in this case.
> > > > > >
> > > > > > Benjamin, Peter, Henrik, any concerns?
> > > > >
> > > > > on the touchpads that support hovering we're already using BTN_TOOL_FINGER
> > > > > together with ABS_DISTANCE, without needing out-of-range reports.
> > > > > BTN_TOUCH is the signal when a finger is physically touching (or ABS_PRESSURE
> > > > > if it exists and clients care about it).
> > > > >
> > > > > So the sequence Charles should send is:
> > > > >
> > > > > 3) <nothing> :)
> > > > > 2)
> > > > >     EV_ABS ABS_DISTANCE <d> # for d > 0
> > > > >     EV_KEY BTN_TOOL_FINGER 1
> > > > >     EV_SYN SYN_REPORT 0
> > > > > 1)
> > > > >     EV_ABS ABS_DISTANCE 0
> > > > >     EV_ABS ABS_X <x>
> > > > >     EV_ABS ABS_Y <y>
> > > > >     ...
> > > > >     EV_KEY BTN_TOUCH 1
> > > > >     EV_SYN SYN_REPORT 0
> > > > > 2)
> > > > >     EV_ABS ABS_DISTANCE <d> # for d > 0
> > > > >     EV_KEY BTN_TOUCH 0
> > > > >     EV_SYN SYN_REPORT 0
> > > > > 3)
> > > > >     EV_KEY BTN_TOOL_FINGER 0
> > > > >     EV_SYN SYN_REPORT 0
> > > > >
> > > > > This should work with at least libinput, though I have to check what happens
> > > > > when you don't send x/y on the first event. I think this would need a patch
> > > > > in libinput, but that's doable. And it's the same sequence we also use for
> > > > > e.g. pen tools that support hovering as well.
> > > > >
> > > > > Cheers,
> > > > >    Peter
> > > > 
> > > > Hi Peter,
> > > > 
> > > > It looks like you're suggesting to use "BTN_TOOL_FINGER" as a signal
> > > > as to weather or not the value in "ABS_DISTANCE" is valid or not.
> > > > 
> > > > 1. No finger detected anywhere:
> > > >     BTN_TOOL_FINGER = 0
> > > >     ABS_DISTANCE = n/a
> > > > 2. Finger seen hovering but not touching:
> > > >     BTN_TOOL_FINGER = 1
> > > >     ABS_DISTANCE > 0
> > > > 2. Finger touching:
> > > >     BTN_TOOL_FINGER = 1
> > > >     ABS_DISTANCE = 0
> > > 
> > > you should set BTN_TOUCH here. This can be done based on some magic pressure
> > > threshold if you have pressure, otherwise just unconditionally set it
> > > whenever distance is 0.
> > > 
> > > > 
> > > > Am I understanding that correctly?
> > > 
> > > yes, but IMO better to think it this way: BTN_TOOL_FINGER signals whether a
> > > finger is detected by the device. everything else is just axis information
> > > if and when it becomes available.
> > > likewise, BTN_TOUCH signals whether the current tool (could be something
> > > other than finger) logically touches the surface.
> > 
> > I wonder if this will not confuse clients that do not pay attention to
> > ABS_DISTANCE though... I take it that libinput and x synaptics drivers
> > won't be confused, mousedev in kernel relies on BTN_TOUCH, what about
> > others?
> 
> if they get confused, they'd already be confused by a set of current
> devices. This isn't new behaviour, we've been doing this for quite a while.
> and as I said above, it matches the behaviour we use for BTN_TOOL_PEN, it's
> IMO hard to justify that the behaviour should be different between the two
> tools.

OK, fair enough. Any chance I could get a patch for ABS_DISTANCE section
of Documentation/input/event-codes.txt to mention that we expect
to see BTN_TOOL_* as well?

Thanks.

-- 
Dmitry

[PATCH] Documentation: event-codes.txt: clarify we want BTN_TOOL_<name> on proximity

[Peter Hutterer]

This explicitly states behavior we already use for some touchpads and tablet
devices.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
---
 Documentation/input/event-codes.txt | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/input/event-codes.txt b/Documentation/input/event-codes.txt
index 3f0f5ce..36ea940 100644
--- a/Documentation/input/event-codes.txt
+++ b/Documentation/input/event-codes.txt
@@ -173,6 +173,10 @@ A few EV_ABS codes have special meanings:
     proximity of the device and while the value of the BTN_TOUCH code is 0. If
     the input device may be used freely in three dimensions, consider ABS_Z
     instead.
+  - BTN_TOOL_<name> should be set to 1 when the tool comes into detectable
+    proximity and set to 0 when the tool leaves detectable proximity.
+    BTN_TOOL_<name> signals the type of tool that is currently detected by the
+    hardware and is otherwise independent of ABS_DISTANCE and/or BTN_TOUCH.
 
 * ABS_MT_<name>:
   - Used to describe multitouch input events. Please see
-- 
2.5.0

Re: Question about ABS_DISTANCE's intended usage.

[Charles Mooney]

On Tue, Feb 23, 2016 at 3:08 PM, Dmitry Torokhov
<dmitry.torokhov@gmail.com> wrote:
> On Wed, Feb 24, 2016 at 08:39:15AM +1000, Peter Hutterer wrote:
>> On Tue, Feb 23, 2016 at 02:02:45PM -0800, Dmitry Torokhov wrote:
>> > On Tue, Feb 23, 2016 at 08:04:32AM +1000, Peter Hutterer wrote:
>> > > On Mon, Feb 22, 2016 at 08:35:31AM -0800, Charles Mooney wrote:
>> > > > On Sun, Feb 21, 2016 at 2:04 PM Peter Hutterer <peter.hutterer@who-t.net> wrote:
>> > > > >
>> > > > > On Thu, Feb 18, 2016 at 10:19:30AM -0800, Dmitry Torokhov wrote:
>> > > > > > On Tue, Feb 09, 2016 at 01:56:05PM -0800, Charles Mooney wrote:
>> > > > > > > Hello all,
>> > > > > > >
>> > > > > > > I'm currently working with a touchpad vendor with a new device that
>> > > > > > > supports a limited form of hover detection.  Their sensor is able to
>> > > > > > > detect the presence or absence of a finger/hand/palm hovering over the
>> > > > > > > sensor without touching it, but is unable to report any more details
>> > > > > > > about it.  This is a more limited form of hover detection than some
>> > > > > > > devices which attach a hover state to each finger they see, and can
>> > > > > > > even report x/y coordinates to hovering finger.
>> > > > > > >
>> > > > > > > Instead of using ABS_MT_DISTANCE, it appears that the correct event to
>> > > > > > > use would be ABS_DISTANCE, since the value is not tied to a specific
>> > > > > > > finger.  I would like to check with you all about how this value is
>> > > > > > > intended to be used, because it's not quite as obvious to me as I
>> > > > > > > first thought.
>> > > > > > >
>> > > > > > > We need to handle three basic states:
>> > > > > > >   1. At least one finger is touching the pad.
>> > > > > > >   2. Something is hovering, but nothing is actually touching.
>> > > > > > >   3. Nothing is touching the pad and nothing is detected hovering over it either
>> > > > > > >
>> > > > > > > It's seems clear to me that an ABS_DISTANCE of zero should indicate
>> > > > > > > state #1 and that any other legal positive value should indicate state
>> > > > > > > #2, but I'm less clear on what the best way to handle state #3 is.
>> > > > > > > Currently, I think the best strategy would be to use a value of
>> > > > > > > ABS_DISTANCE = -1 to indicate that there are no fingers seen (hovering
>> > > > > > > or otherwise), does that make sense?
>> > > > > > >
>> > > > > > > If not this, how else would you suggest that this ought to be done?
>> > > > > >
>> > > > > > As we discussed in person, I believe that reporting an "out of bounds"
>> > > > > > value for ABS_DISTANCE when we have to use single-touch mode and thus do
>> > > > > > not have a good way to invalidate a contact, is the easiest option.
>> > > > > > Alternative would be to invent another SYN event, which I'd rather not.
>> > > > > >
>> > > > > > So for devices that support hovering but can not report individual
>> > > > > > hovering contacts we should declare 0..N as ABS_DISTANCE range and report
>> > > > > > following values:
>> > > > > >
>> > > > > >  - 0 when a finger is actually touching
>> > > > > >  - 1..N for hovering fingers
>> > > > > >  - return X < 0 or X > N when no fingers are detected at all; in
>> > > > > >    practice I think we should simply report -1 in this case.
>> > > > > >
>> > > > > > Benjamin, Peter, Henrik, any concerns?
>> > > > >
>> > > > > on the touchpads that support hovering we're already using BTN_TOOL_FINGER
>> > > > > together with ABS_DISTANCE, without needing out-of-range reports.
>> > > > > BTN_TOUCH is the signal when a finger is physically touching (or ABS_PRESSURE
>> > > > > if it exists and clients care about it).
>> > > > >
>> > > > > So the sequence Charles should send is:
>> > > > >
>> > > > > 3) <nothing> :)
>> > > > > 2)
>> > > > >     EV_ABS ABS_DISTANCE <d> # for d > 0
>> > > > >     EV_KEY BTN_TOOL_FINGER 1
>> > > > >     EV_SYN SYN_REPORT 0
>> > > > > 1)
>> > > > >     EV_ABS ABS_DISTANCE 0
>> > > > >     EV_ABS ABS_X <x>
>> > > > >     EV_ABS ABS_Y <y>
>> > > > >     ...
>> > > > >     EV_KEY BTN_TOUCH 1
>> > > > >     EV_SYN SYN_REPORT 0
>> > > > > 2)
>> > > > >     EV_ABS ABS_DISTANCE <d> # for d > 0
>> > > > >     EV_KEY BTN_TOUCH 0
>> > > > >     EV_SYN SYN_REPORT 0
>> > > > > 3)
>> > > > >     EV_KEY BTN_TOOL_FINGER 0
>> > > > >     EV_SYN SYN_REPORT 0
>> > > > >
>> > > > > This should work with at least libinput, though I have to check what happens
>> > > > > when you don't send x/y on the first event. I think this would need a patch
>> > > > > in libinput, but that's doable. And it's the same sequence we also use for
>> > > > > e.g. pen tools that support hovering as well.
>> > > > >
>> > > > > Cheers,
>> > > > >    Peter
>> > > >
>> > > > Hi Peter,
>> > > >
>> > > > It looks like you're suggesting to use "BTN_TOOL_FINGER" as a signal
>> > > > as to weather or not the value in "ABS_DISTANCE" is valid or not.
>> > > >
>> > > > 1. No finger detected anywhere:
>> > > >     BTN_TOOL_FINGER = 0
>> > > >     ABS_DISTANCE = n/a
>> > > > 2. Finger seen hovering but not touching:
>> > > >     BTN_TOOL_FINGER = 1
>> > > >     ABS_DISTANCE > 0
>> > > > 2. Finger touching:
>> > > >     BTN_TOOL_FINGER = 1
>> > > >     ABS_DISTANCE = 0
>> > >
>> > > you should set BTN_TOUCH here. This can be done based on some magic pressure
>> > > threshold if you have pressure, otherwise just unconditionally set it
>> > > whenever distance is 0.
>> > >
>> > > >
>> > > > Am I understanding that correctly?
>> > >
>> > > yes, but IMO better to think it this way: BTN_TOOL_FINGER signals whether a
>> > > finger is detected by the device. everything else is just axis information
>> > > if and when it becomes available.
>> > > likewise, BTN_TOUCH signals whether the current tool (could be something
>> > > other than finger) logically touches the surface.
>> >
>> > I wonder if this will not confuse clients that do not pay attention to
>> > ABS_DISTANCE though... I take it that libinput and x synaptics drivers
>> > won't be confused, mousedev in kernel relies on BTN_TOUCH, what about
>> > others?
>>
>> if they get confused, they'd already be confused by a set of current
>> devices. This isn't new behaviour, we've been doing this for quite a while.
>> and as I said above, it matches the behaviour we use for BTN_TOOL_PEN, it's
>> IMO hard to justify that the behaviour should be different between the two
>> tools.
>
> OK, fair enough. Any chance I could get a patch for ABS_DISTANCE section
> of Documentation/input/event-codes.txt to mention that we expect
> to see BTN_TOOL_* as well?
>
> Thanks.
>
> --
> Dmitry

Very good, thank you all for your help and clarification.  I will work
with our vendor to make sure their touchpads follow this pattern so it
works smoothly with everyone else as well.

Thanks!
Charlie Mooney

Re: [PATCH] Documentation: event-codes.txt: clarify we want BTN_TOOL_<name> on proximity

[Peter Hutterer]

On Wed, Feb 24, 2016 at 02:12:03PM +1000, Peter Hutterer wrote:
> This explicitly states behavior we already use for some touchpads and tablet
> devices.
> 
> Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
> ---
>  Documentation/input/event-codes.txt | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/Documentation/input/event-codes.txt b/Documentation/input/event-codes.txt
> index 3f0f5ce..36ea940 100644
> --- a/Documentation/input/event-codes.txt
> +++ b/Documentation/input/event-codes.txt
> @@ -173,6 +173,10 @@ A few EV_ABS codes have special meanings:
>      proximity of the device and while the value of the BTN_TOUCH code is 0. If
>      the input device may be used freely in three dimensions, consider ABS_Z
>      instead.
> +  - BTN_TOOL_<name> should be set to 1 when the tool comes into detectable
> +    proximity and set to 0 when the tool leaves detectable proximity.
> +    BTN_TOOL_<name> signals the type of tool that is currently detected by the
> +    hardware and is otherwise independent of ABS_DISTANCE and/or BTN_TOUCH.
>  
>  * ABS_MT_<name>:
>    - Used to describe multitouch input events. Please see
> -- 
> 2.5.0
 
almost forgot about this one, Dmitry, you happy with this one?

Cheers,
   Peter

Re: [PATCH] Documentation: event-codes.txt: clarify we want BTN_TOOL_<name> on proximity

[Dmitry Torokhov]

On Wed, Feb 24, 2016 at 02:12:03PM +1000, Peter Hutterer wrote:
> This explicitly states behavior we already use for some touchpads and tablet
> devices.
> 
> Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

Applied, thank you.

> ---
>  Documentation/input/event-codes.txt | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/Documentation/input/event-codes.txt b/Documentation/input/event-codes.txt
> index 3f0f5ce..36ea940 100644
> --- a/Documentation/input/event-codes.txt
> +++ b/Documentation/input/event-codes.txt
> @@ -173,6 +173,10 @@ A few EV_ABS codes have special meanings:
>      proximity of the device and while the value of the BTN_TOUCH code is 0. If
>      the input device may be used freely in three dimensions, consider ABS_Z
>      instead.
> +  - BTN_TOOL_<name> should be set to 1 when the tool comes into detectable
> +    proximity and set to 0 when the tool leaves detectable proximity.
> +    BTN_TOOL_<name> signals the type of tool that is currently detected by the
> +    hardware and is otherwise independent of ABS_DISTANCE and/or BTN_TOUCH.
>  
>  * ABS_MT_<name>:
>    - Used to describe multitouch input events. Please see
> -- 
> 2.5.0
> 

-- 
Dmitry