@deshipu may want to review as well.

@xiongyihui This looks good as it stands. Do you still consider it a draft, or have you finished your testing?

I have tested it. It works well. I would use it in the M60 keyboard. Do you have any other ideas?

I'm wondering if we should call this out_report or received_report to distinguish it from the regular IN report. What do you think the best terminology is?

If we do not consider to add a out_report property to usb_hid.Device, I would prefer to use report. Otherwise, would use out_report and in_report.

@xiongyihui We have send_report(), which sends the IN report (obviously). Since there is no receive_report(), I was thinking the .report property should be .out_report(), to distinguish it from the IN report, since the OUT data in .report is not the same as the IN data send by send_report().

Use it as a function or a property? Maybe like DigitalInOut.value

I think a property would be best. It would return the latest report received.

I do like send_report() since it is sending a stream of reports, not setting a value over and over. I don't think .report = next report is the right thing to do.

Then .report is a read-only property. But to distinguish the incoming (OUT) report from the outgoing (IN) report, I am suggesting calling it received_report. (The "OUT" vs "IN" designations are very confusing to the layperson, since they reflect the host's view.)

If you use a property, people will be encouraged to use it in multiple conditions, and will be surprised when its value changes in between them. A function call encourages you to assign the returned value to a variable and work with that variable.

I tend to agree with this, even though we have DigitalInOut.value, _bleio.Characteristic.value, etc. However, would receive_report() hang until there was a received OUT report?

I think send_report() is fine as-is. I think @dhalbert's proposal is a property received_report that is the most recently received report (not a function as you suggest @deshipu.)

My one concern is if folks use HID as a serial-like transport and need every HID out report buffered. I think it's an abuse of the protocol but may still be done.

I was proposing an actual function; I didn't really think about the hanging part. It could return None if no report was available.

We have a long-term interest in using HID RAW reports for communication with a host, because all hosts already support HID RAW natively and don't need drivers. That would require real FIFO support, so I would lean toward a function. It does not have to buffer for now; we can add that later.

I am all for a function and adding FIFO in the future.
Report can be used to exfiltrate data from a computer (back to what pretend to be a USB keyboard).
To have a good bandwidth, you need to make sure no data is lost in those "LED" report.

For USB keyboard, losing some LED reports is not a big deal. We just need to show the latest LED status.
For HID RAW report, It would be different, as it would probably not use report IDs.

Let's try to finish this off. @xiongyihui I think you are right about the report ID's: they cannot be used for raw mode. Are you saying you still prefer a property, or that the received_report() function is not applicable for raw mode? I don't know if there are non-raw examples of OUT reports that should be FIFO'd.

The implementation of USB_HID depends on report IDs. It would be very difficult to add a raw mode to USB_HID.
Maybe add a new module USB_RAW_HID and an USB interface to support HID RAW, or use WebUSB instead of HID RAW.
I don't think we should consider raw mode or FIFO here, so I still prefer a property.

That is clear thinking, thanks. OK, how about calling it .last_received_report? That makes it clear it's not related to outgoing reports, and is not FIFO'd.

I'm OK with .last_received_report.