diff --git a/embedded-workshop-book/src/advanced-next-steps.md b/embedded-workshop-book/src/advanced-next-steps.md index f5a4fa4..a932888 100644 --- a/embedded-workshop-book/src/advanced-next-steps.md +++ b/embedded-workshop-book/src/advanced-next-steps.md @@ -22,6 +22,7 @@ If you'd like to continue working on your workshop project, we recommend adding ✅ To verify that string descriptors are working in a cross-platform way, extend the `print-descs` program to also print the device's string descriptors. See the [`read_string_descriptor`] method but note that this must be called on a "device handle", which is what the commented out `open` operation does. [`read_string_descriptor`]: https://docs.rs/rusb/0.6.2/rusb/struct.DeviceHandle.html#method.read_string_descriptor +[usb_spec]: https://www.usb.org/document-library/usb-20-specification ## Explore more RTIC features diff --git a/embedded-workshop-book/src/device-descriptor.md b/embedded-workshop-book/src/device-descriptor.md index 0a04d06..9231f62 100644 --- a/embedded-workshop-book/src/device-descriptor.md +++ b/embedded-workshop-book/src/device-descriptor.md @@ -10,7 +10,9 @@ Inside the 'interface 0' rectangle there are three rectangles labeled 'endpoint After receiving a GET_DESCRIPTOR request during the SETUP stage the device needs to respond with a *descriptor* during the DATA stage. -A descriptor is a binary encoded data structure sent by the device to the host. The device descriptor, in particular, contains information about the device, like its product and vendor identifiers and how many *configurations* it has. The format of the device descriptor is specified in section 9.6.1, Device, of the USB specification. +A descriptor is a binary encoded data structure sent by the device to the host. The device descriptor, in particular, contains information about the device, like its product and vendor identifiers and how many *configurations* it has. The format of the device descriptor is specified in section 9.6.1, Device, of the [USB specification][usb_spec]. + +[usb_spec]: https://www.usb.org/document-library/usb-20-specification As far as the enumeration process goes, the most relevant fields of the device descriptor are the number of configurations and `bcdUSB`, the version of the USB specification the devices adheres to. In `bcdUSB` you should report compatibility with USB 2.0. diff --git a/embedded-workshop-book/src/getting-device-configured.md b/embedded-workshop-book/src/getting-device-configured.md index 3de1585..cb08e24 100644 --- a/embedded-workshop-book/src/getting-device-configured.md +++ b/embedded-workshop-book/src/getting-device-configured.md @@ -16,13 +16,15 @@ Now modify the `print-descs` program to "open" the device -- this operation is c ## SET_CONFIGURATION -The SET_CONFIGURATION request is sent by the host to configure the device. Its configuration according to section 9.4.7. of the USB spec is: +The SET_CONFIGURATION request is sent by the host to configure the device. Its configuration according to section 9.4.7. of the [USB specification][usb_spec] is: -- `bmrequesttype` is 0b00000000 -- `brequest` is SET_CONFIGURATION +- `bmrequesttype` is **0b00000000** +- `brequest` is **9** (i.e. the SET_CONFIGURATION Request Code, see table 9-4 in the USB spec) - `wValue` contains the requested configuration value - `wIndex` and `wLength` are 0, there is no `wData` +[usb_spec]: https://www.usb.org/document-library/usb-20-specification + ✅ To handle a SET_CONFIGURATION, do the following: - If the device is in the `Default` state, you should stall the endpoint because the operation is not permitted in that state. diff --git a/embedded-workshop-book/src/references-resources.md b/embedded-workshop-book/src/references-resources.md index 7c847bb..a0fd3ce 100644 --- a/embedded-workshop-book/src/references-resources.md +++ b/embedded-workshop-book/src/references-resources.md @@ -17,7 +17,7 @@ It is also recommended that you work through the advanced material of this cours ## Advanced Material - [nRF52840 Product Specification 1.1](https://infocenter.nordicsemi.com/pdf/nRF52840_PS_v1.1.pdf) -- [Universal Serial Bus Specification Revision 2.0](https://www.usb.org/document-library/usb-20-specification) +- [Universal Serial Bus (USB) Specification Revision 2.0](https://www.usb.org/document-library/usb-20-specification) ## When's The Next Workshop? If you've enjoyed this workshop and would like to join us for another one, [subscribe to our newsletter](https://ferrous-systems.us19.list-manage.com/subscribe/post?u=94954b16eab55b59525c890cb&id=5eaf5b14e6)! This is where we'll announce upcoming public courses. diff --git a/embedded-workshop-book/src/set-address.md b/embedded-workshop-book/src/set-address.md index b5b94a2..777ce6a 100644 --- a/embedded-workshop-book/src/set-address.md +++ b/embedded-workshop-book/src/set-address.md @@ -4,8 +4,8 @@ A SET_ADDRESS request has the following fields as defined by Section 9.4.6 Set Address of the USB spec: -- `bmrequesttype` is 0b00000000 -- `brequest` is SET_ADDRESS +- `bmrequesttype` is **0b00000000** +- `brequest` is **5** (i.e. the SET_ADDRESS Request Code, see table 9-4 in the USB spec) - `wValue` contains the address to be used for all subsequent accesses - `wIndex` and `wLength` are 0, there is no `wData` diff --git a/embedded-workshop-book/src/setup-stage.md b/embedded-workshop-book/src/setup-stage.md index c4e334f..4fb1fb6 100644 --- a/embedded-workshop-book/src/setup-stage.md +++ b/embedded-workshop-book/src/setup-stage.md @@ -17,11 +17,13 @@ The definition of `Descriptor::Configuration` as well as the associated test has ❗️ Keep the cable connected to the J3 port for the rest of the workshop -Start with the GET_DESCRIPTOR request, which is described in detail in section 9.4.3 of the USB specification. All the constants you will need are described in Tables 9-3, 9-4 and 9-5. +Start with the GET_DESCRIPTOR request, which is described in detail in section 9.4.3 of the [USB specification][usb_spec]. All the constants we'll be using are also described in Tables 9-3, 9-4 and 9-5 of the USB spec. + +[usb_spec]: https://www.usb.org/document-library/usb-20-specification The fields of a GET_DESCRIPTOR request are as follows: -- `bmRequestType` is 0b10000000 -- `bRequest` is GET_DESCRIPTOR +- `bmRequestType` is **0b10000000** +- `bRequest` is **6** (i.e. the GET_DESCRIPTOR Request Code, see table 9-4 in the USB spec) - the high byte of `wValue` contains the descriptor type, whereas the low byte contains the descriptor index - `wIndex` is set to 0 for our purposes @@ -33,7 +35,7 @@ To complete the task, proceed like this: 1. **Parse GET_DESCRIPTOR requests:** Modify `Request::parse()` in `advanced/common/usb/src/lib.rs` to recognize a GET_DESCRIPTOR request so that the `get_descriptor_device` test passes. Note that the parser already handles SET_ADDRESS requests. - - check table 9-4 in the USB specification for Request Codes + - remember the GET_DESCRIPTOR fields described at the start of this section - remember that you can define binary literals by prefixing them with `0b` - you can use bit shifts (`>>`) and casts (`as u8`) to get the high/low bytes of a `u16`