Better Keyboard detection of individual taps

[Justin-Fisher]

The current webots keyboard device reports only whether keys are currently down. Even for fast typists, most keytaps leave the key down for multiple timesteps. In many instances, controller coders would like to trigger events once per key-tap (not once per timestep the key remains down), so they would like to know whether a key has just been pressed (or just been released), rather than just whether it is currently down.

One easy way of making such information available would be by offering a list of newly pressed keys (ones that are down now but weren't down the last timestep) and a list of newly released keys (ones that aren't down now, but were down last timestep). [Another idea that Olivier and I discussed on discord would be to instead set up a functionality by which the keyboard device can report which characters keystrokes have created, which hopefully would report each keytap just once. But that would be a much bigger change than the simple one I'm suggesting here, and both could be done.]

I currently use code like the following to do this in Python (and I set up a subclass of Keyboard to automatically do this for all my Python controllers). I would suggest though that this functionality should probably just be made part of the keyboard device itself, and accessed through the API with something like keyboard.getPressedKey() and keyboard.getReleasedKey(), rather than making a bunch of coders each figure out how to do this on our own in different languages.

       oldKeys = currentKeys                            # remember what used to be the current keys
       currentKeys = set()                                   # start with an empty set
       key = keyboard.getKey()                           # read first key that is down
       while key != -1:                                         # -1 means no more keys are down
           currentKeys.add(key)                            # add this new key into the set
           key = keyboard.getKey()                      # read next key that is down
       releasedKeys = oldKeys - currentKeys      # Python's set subtraction--yay!
       pressedKeys  = currentKeys - oldKeys

[omichel]

So, from an API point of view, how would you propose this feature? Like a new keyboard API function?

  keyboard.getNewlyPressedKeys()  # return only the keys pressed since last call to this method
  keyboard.getNewlyReleasedKeys()  # return only the keys released since last call to this method

Which would return list of keys?
How would you implement this in C?
What kind of data type could the equivalent C function return?

[Justin-Fisher]

As a first guess, I would suggest implementing these in the same way as you implement keyboard.getKey, i.e., by returning the keys one at a time, and then returning -1 when there are no more keys. For backwards-compatibility reasons, you probably aren't going to change the interface for getKey, and if you aren't going to change that, you'd probably want to keep this interface similar. So I would suggest:

  keyboard.getPressedKey()   # return another key that was newly pressed, or -1 if there is no such key
  keyboard.getReleasedKey()  # return another key that was newly released, or -1 if there is no such key

(I cut the "Newly" as it seemed unnecessary, and made Keys be Key since this would return the keys one at a time, just like getKey does.)

[Justin-Fisher]

One issue you'll need to sort out is whether you want to retain the keys over multiple timesteps if a controller neglects to access them (e.g. because the simulation is asynchronous and it was running slow). I guess my inclination would be just to build up a queue of keys to return, adding to it every timestep, and return all of them in order whenever a controller gets around to asking for them. (Probably you'd have a buffer length-limit for how many keys could be queued this way.)

[omichel]

OK, I see. That's indeed a good design and should be fairly easy to implement, and easy to understand if documented properly.
May I let you try to implement it? You should start up with the C API, e.g., wb_keyboard_get_pressed_key() and wb_keyboard_get_released_key() in webots/src/Controller/api/keyboard.c. The complete procedure to add a new API function is described here: https://github.com/cyberbotics/webots/wiki/Adding-New-Node-and-API-Function#adding-a-new-api-function. I will be happy to review your upcoming PR about it!

[Justin-Fisher]

I won't be able to get to this any time soon (too much else on my platter!), plus my C is pretty rusty (e.g., even simple data structures like a queue or set-subtraction in C would take me some effort to implement efficiently). Also, I don't really have much motivation to make this change myself since I already made a Keyboard subclass that already does all this stuff automatically for my Python controllers. I just thought I'd suggest this as a way to give other coders, esp. ones using other languages, access to functionality I found useful.

[omichel]

All right. This is not in our priorities list either, so I will close the issue for now, but it will be still be findable in case somebody needs your code. Alternatively you could also publish your code snippet in the keyboard API documentation.

[Justin-Fisher]

The message I'm getting from this is, "Don't bother making suggestions, even if they're ones that would be easy to implement and useful to many users, unless you're willing to make those changes yourself." Is that not the right message for me to get?

(Maybe it would be better if you had something like a "low priority" or "good first issue" label for suggestions like this, to indicate that these are things that it'd be good if somebody got around to eventually, rather than labeling them "wontfix", which suggests that there was no point in making the suggestion in the first place.)

[omichel]

Actually, we are a bit afraid to get overwhelmed by suggestions and obviously we cannot afford to follow-up and implement all of them, even if they make sense. It's easier to suggest than to actually do things. I didn't want to discourage suggestions. But your idea on how to handle this sounds good. So, I created a "low priority" label and added the "good first issue" label to this issue which I re-opened. The message should now be clearer.