Skip to content

Add information on power saving options for USB components #1154

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 17, 2019
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/api/usb/usb_component.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,3 +87,9 @@ int main(void)
The `connect()` and `disconnect()` functions control the state of the physical USB line to the host. When a device is connected, it is visible to the host PC to which it is attached. Once connected, the host PC must finish setup.

USB components provide at least one service. When a service is available for use, it is `ready`. For example, the USBSerial component enters the `ready` state after a serial port has been opened on the host PC. To determine whether a USB component's service is ready, you can use the `ready()` function. It returns `true` if the USB component is ready for use and `false` otherwise. Some components provide multiple services, such as USBAudio, which can send or receive data and has two separate ready functions - `read_ready()` and `write_ready()`. Furthermore, for each `ready()` function, there is also a corresponding `wait_ready()` function, which you can use to block until the USB component's service is available.

## USB component and power saving

Some instantiated USB components prevent devices from going to deep sleep because their `USBPhyHw` implentation holds a deep sleep lock. You can temporarily disable USB using `USBDevice::deinit()` to permit deep sleep. However, you must make sure all the data transfers have concluded to avoid any data corruption. The USB host controls the enumeration process, so it chooses when and how to restore the device. Even if the device state is returned to what it was before the disconnect, the host PC software may not be where it left off - for example, you may need to reopen a serial port.

You can use `USBDevice::connect()` to resume USB component operation when USB power is detected after it was previously suspended through `USBDevice::deinit()`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you suggest a way to rephrase this sentence? I had to read it a few times for it to make sense.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do not mind your edit if it removes the confusion.