Added power tracking api

[purdeaandrei]

Description

This has now been tested on chibios, running on an STM32F446, and atmega32u4, and atmega32u2.

Types of Changes

• Core
• Bugfix
• New feature
• Enhancement/optimization
• Keyboard (addition or update)
• Keymap/layout/userspace (addition or update)
• Documentation

Issues Fixed or Closed by This PR

Checklist

• My code follows the code style of this project: C, Python
• I have read the PR Checklist document and have made the appropriate changes.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• I have tested the changes and verified that they work and don't break anything (as well as I can manage).

[purdeaandrei]

Tested on STM32F446, and atmega32u4, and atmega32u2.

[drashna]

While the code looks good, "power tracking" doesn't sound right to me.

The point is getting the status from USB, correct? Then maybe "USB Power State" would be more accurate, maybe?

That said, I know that naming stuff is hard. I have some truly atrociously named stuff that has made it into core, so I definitely understand that.

[stale]

Thank you for your contribution!
This pull request has been automatically marked as stale because it has not had activity in the last 45 days. It will be closed in 30 days if no further activity occurs. Please feel free to give a status update now, or re-open when it's ready.
For maintainers: Please label with awaiting review, breaking_change, in progress, or on hold to prevent the issue from being re-flagged.

[purdeaandrei]

@drashna
I have rebased the branch on top of latest develop.
I have also renamed power to usb_power. So for example the main .c file is now quantum/usb_power.c, and the main variable holding the usb power state is called "usb_power_state".
The word 'tracking' is not in the source code content, only in some commit messages, the branch name, and the PR description.

Let me know if any further changes are needed.
Note: I have not yet tested this since the rebase. I will test soon, and I will drop another comment here when that happens.

[drashna]

Honestly, i'm still not too happy with the naming, as it doesn't really reflect what it is.

usb_device_state_* feels much more accurate of a name for this (and is similar to the LUFA and ChibiOS event names, to boot).

[purdeaandrei]

@drashna Renamed as you suggested.

[purdeaandrei]

I re-tested the current version of a branch on an STM32F446-based keyboard.
I set the locklights to output the usb_device_state enum every time it changes.
On connection to a linux pc I observed:
USB_DEVICE_STATE_INIT -> USB_DEVICE_STATE_SUSPEND -> USB_DEVICE_STATE_INIT -> USB_DEVICE_STATE_CONFIGURED
I observed the same as above on connection to an Android phone.

On the computer suspending I observed:
USB_DEVICE_STATE_CONFIGURED -> USB_DEVICE_STATE_SUSPEND

On the computer exiting suspend I observed:
USB_DEVICE_STATE_SUSPEND -> USB_DEVICE_STATE_CONFIGURED

On the 1Amp port of a 'powerzilla' power bank I observed: USB_DEVICE_STATE_INIT -> USB_DEVICE_STATE_SUSPEND
On the 2.1Amp port of the same power bank I ovserved the keyboard staying in USB_DEVICE_STATE_INIT forever.

Note: since I didn't analyze this with a logical analyzer, in theory there could be super fast state transitions that I missed with my eyes.

[purdeaandrei]

Rebased (not cause this PR needed it, but because the dependent 12692 PR had a conflict)

[tzarc]

Can you explain the unused configurationNumber parameters?

[purdeaandrei]

@tzarc In general, the configuration number matters to how much power the USB device is allowed to consume, because each USB device could have multiple configurations, only one of which is selected at any point in time (or none if not configured).
Each configuration descriptor has its own ".MaxPowerConsumption", so you could have in theory one configuration that consumes 500mA, and one that consumes only 100mA. At the moment everything is using just one configuration in QMK, so that's why it's unused for now.

One possible usecase in the future would be, if a keyboard has a 500mA-using solenoid driver, it could have one configuration to select 500mA, and another one to select 100mA, and disable the solenoid driver automatically, or set it into a 100mA current-limited mode. So when you plug the keyboard into a normal USB port, or powered hub, you get full solenoid operation, but in an unpowered usb hub, the solenoid is automatically disabled, or in slower current-limited mode.

Or in case of keyboards with high current-consumption backlights, it could throttle the backlight intensity when plugged into a 100mA-only port.

I'm not 100% sure if default HID operating system drivers are smart enough to select the alternative 100mA configuration, when they can't enable the 500mA one, or if they will just disable the USB device, so my specific example may not be a good one, but it's still worth keeping the interface, even if my example doesn't actually work in the real world, just in case we will add multiple-configuration support in the future for other reasons.