Proposal

Proposed new joystick message

Proposal 1

Header header
string joystick_name
float32[] axes
int32[] axes_identifier
bool[] buttons
int32[] buttons_identifier
# A bunch of constants for the identifiers.

Proposal 2

Header header
string joystick_name
float32 value
uint8 type
uint32 identifier
# A bunch of constants for the identifiers.

Comments

• The joystick name should be unique to a particular joystick node, and could be if we decide to multiplex multiple joysticks on a single message.
• axes should return the value that is output by the joystick without flipping it. For some reason lost in time, the current joy_node flips the sign of all the axes.
• axes_identifier and buttons_identifier are integers that indicate the normal use of the corresponding button/axis. Many josticks provide it, so it is too bad that we are just throwing away the information. I am thinking that the list in /u/blaise/temp/linux-2.6.32/include/linux/input.h is the way to go. I believe that it is standardized for HID devices, but need to verify that. An excerpt of that file follows:

/*
 * Keys and buttons
 *
 * Most of the keys/buttons are modeled after USB HUT 1.12
 * (see http://www.usb.org/developers/hidpage).
 * Abbreviations in the comments:
 * AC - Application Control
 * AL - Application Launch Button
 * SC - System Control
 */

#define KEY_RESERVED            0
#define KEY_ESC                 1
#define KEY_1                   2
...
#define BTN_MISC                0x100
#define BTN_0                   0x100
#define BTN_1                   0x101
...
#define BTN_LEFT                0x110
#define BTN_RIGHT               0x111
#define BTN_MIDDLE              0x112
#define BTN_SIDE                0x113
...
/*
 * Absolute axes
 */

#define ABS_X                   0x00
#define ABS_Y                   0x01
#define ABS_Z                   0x02
...
#define ABS_THROTTLE            0x06
#define ABS_RUDDER              0x07
#define ABS_WHEEL               0x08
#define ABS_GAS                 0x09

API review

Proposer: Blaise Gassend

Present at review:

• List reviewers

Question / concerns / comments

Enter your thoughts on the API and any questions / concerns you have here. Please sign your name. Anything you want to address in the API review should be marked down here before the start of the meeting.

Blaise

• Should we more closely follow what HID devices do, with buttons, absolute axes and relative axes? That way mice could also fit in this message. It could be a HID message.
• How do we handle analog buttons? As an axis? Do we want to try to make them look like buttons?
  • Currently ps3joy outputs most of its buttons both as axes and as buttons.
• Using identifiers requires iterating through the whole array can we get around that somehow?
• We might want to define sub-messages rather than having multiple equal-length arrays.
• Is the joystick_name field a good idea?

Josh

• I don't like joystick_name -- this is what multiple topics are for.
• Instead of a bunch of separate arrays, I'd like to see something like:

JoyElement.msg:
float32 value
int32 identifier

bool onoff
bool analog

Joy.msg:
JoyElement[] elements

• The names would likely be different, but this would allow a single set of "elements" (I don't like that term either) that are analog or not. Non-analog buttons would still set value to 0/1.
• I like the idea of a HID message.

Eric

• I also don't like the idea of the name. This makes the remapping rules stop working well, and I don't think there's a big win from it.
• The two options you lay out at the beginning raise an interesting question (full state update vs. event messages), but I'm in favor of the full state update for two reasons:
  • my intuition is that full-state updates will be more intuitive to use since they won't require the recipient of the data to do as much work to track the state of the axes / buttons that aren't moving
  • Probably more important, since we can drop messages when buffers fill up, we're not guaranteed that all events will get through, so the event-based approach can lead to inconsistent state that persists over time.
• I like the idea of a more powerful/general representation of the full HID spec, but want to make sure that the joystick message remains very easy to use, and don't want to try to grow joystick to encompass everything else (specifically, including relative axes like mice requires different event processing logic and tracking that I don't want to require joystick users to think about)
• Adding the identifier of the joystick type might be useful, to allow profiles per joystick-type. I think this is likely to be more useful than the identifier logic, since getting that to work right across many joysticks requires a lot of testing / smart heuristics / etc, and setting up pre-set profiles for specific devices seems simpler to me. It's also unclear to me how the identifier logic would interact with things like joystick_remapper.
• I like the separate arrays for buttons vs. axes.

I think my proposed interface would be quite close to the current one:

Joy.msg:
String joystick_type   #e.g. PS3
float32 axes[] #always -1 to 1, not flipped from original joystick
float32 buttons[] #always 0 to 1, digital buttons just jump between extremes

And I would propose adding a HID message that is event-based, allows relative changes, passes through identifiers, and requires more software support on the other side.

HID.msg:
HIDEvent[] events

HIDEvent.msg:
int32 identifier
int32 value

This is informed by the linux kernel hiddev_event struct

79             struct hiddev_event {
80                 unsigned hid;
81                 signed int value;
82             };

And this would probably have to be paired with some set of service calls which replicate ioctl functionality, but could be mapped directly to have a ros node on one side which reads from an input device and makes it available over ros and have a node on a remote machine which looks like a local hid device, so that this could be used to map mice or anything else cleanly.

Meeting agenda

To be filled out by proposer based on comments gathered during API review period

Conclusion

Stack status change mark change manifest)

• Action items that need to be taken.

• Major issues that need to be resolved

---