Implement Six Axis HID

[Glodigit]

This is a chunk of #1087.
This PR contains the SpaceMouse Compact-compatible HID implementation and updated boot.md documentation.

[Glodigit]

Not sure what this line accomplishes. I just added it to match with Axis.

[xs5871]

8bit axis can only move 127 units per report and we report movement > 127 in chunks. This part checks if there's no movement left and discards the axis from keys_pressed.

[Glodigit]

I see. For SixAxis, this would be values > 500 units.

[xs5871]

Is it required to have the sixaxis report be split into three?

[Glodigit]

Are you referring to the 3 report IDs? Unfortunately, that's how 3dconnexion implemented it. There used to be 4 on devices predating the SpaceMouse Compact, but now they merge ID 1 and 2 into a single axis report on ID 1. I tried sending the 6 axis report on ID 2 and nothing moved, so it seems that 3DxWare expects specific reports on specific IDs.

I can only imagine these were all legacy decisions carried forward to simplify their long-term driver support.

[xs5871]

A single ID would have simplified things. The conditional send_report is not a very nice solution. It has to run the check every time a report is send and 99% of users will never even use the sixaxis report.

[Glodigit]

That is true. What about something like:

def send(self):
    for report in self.device_map.keys():
        if report.pending:
            try:
                self.device_map[report].send_report(report.buffer)
            except ValueError:
                self.device_map[report].send_report(
                    report.buffer,
                    1 if len(report.buffer) == _REPORT_SIZE_SIXAXIS else 3)
            report.pending = False

[xs5871]

No. We have to build seperability into it. It's planed to dynamically load specific report code based on available endpoints. KMK is too big and slow already.
The best I can come up with right now without refactoring the whole hid code is wrapping the send_report.

class DeviceReportId:
    def __init__(self, device, id):
        self.device = device
        self.id = id

    def send_report(self, buffer):
        self.decive.send_report(buffer, self.id)

# ...
class AbstractHID:
# ...
    def setup_sixaxis_hid(self):
        if device := find_device(self.devices, _USAGE_PAGE_SIXAXIS, _USAGE_SIXAXIS):
            report = SixAxisDeviceReport()
            self.report_map.update(report.get_action_map())
            self.device_map[report] = DeviceReportId(device, 1)
            report = SixAxisDeviceButtonReport()
            self.report_map.update(report.get_action_map())
            self.device_map[report] = DeviceReportId(device, 3)

[Glodigit]

Since the ID is most likely under 255, what about having each buffer be 1 larger and report.buffer[0] (or [-1]) be the ID? Thus you send something like

self.device_map[report].send_report(report.buffer[1:], report.buffer[0])

Another issue is that the IDs need to be known ahead of time (e.g. keyboard might be ID 1 or ID 5).

[xs5871]

My suggestion would only apply to the spacemouse emulation report. The report ID of keyboard and pointer doesn't matter, because they always are seperate endpoints with only one single report buffer. They don't need a wrapper around send_report.

The spacemouse is the exception here. Specifically the vendor specific host software that expects the report to be split into multiple report IDs. According to USB specs there's no reason why sixaxis and buttons, or any disimilar usage pages, couldn't be part of the same report. Every mouse with horizontal scrolling does that.