diff --git a/embedded-workshop-book/src/advanced-next-steps.md b/embedded-workshop-book/src/advanced-next-steps.md index 4dccdd5..f5a4fa4 100644 --- a/embedded-workshop-book/src/advanced-next-steps.md +++ b/embedded-workshop-book/src/advanced-next-steps.md @@ -2,17 +2,24 @@ ## String descriptors -If you'd like to continue working on your workshop project, we recommend adding String Descriptors support to the USB firmware. +If you'd like to continue working on your workshop project, we recommend adding String Descriptors support to the USB firmware. To do this, follow these steps: -- First, you'll want to read through section 9.6.7 of the USB spec, which covers string descriptors. -- Next, we suggest you change your *configuration* descriptor to use string descriptors. You'll want to change the `iConfiguration` field to a non-zero value. Note that this change will likely break enumeration. -- Now, re-run the program to see what new control requests you get from the host. -- You'll need to update the `usb` parser to handle the new requests. -- Then you can extend the logic of `ep0setup` to handle these new requests. -- Eventually, you'll need to send a string descriptor to the host. Note here that Rust string literals are UTF-8 encoded but the USB protocol uses UTF-**16** strings. You'll need to convert between these formats. -- After you have `iConfiguration` working you can start adding strings to other descriptors like the device descriptor e.g. its `iProduct` field. +✅ Read through section 9.6.7 of the USB spec, which covers string descriptors. -To verify that string descriptors are working in a cross-platform way you can 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. + +✅ Change your *configuration* descriptor to use string descriptors. You'll want to change the `iConfiguration` field to a non-zero value. Note that this change will likely break enumeration. + +✅ Re-run the program to see what new control requests you get from the host. + +✅ Update the `usb` parser to handle the new requests. + +✅ Extend the logic of `ep0setup` to handle these new requests. + + Eventually, you'll need to send a string descriptor to the host. Note here that Rust string literals are UTF-8 encoded but the USB protocol uses UTF-**16** strings. You'll need to convert between these formats. + +✅ If this works, add strings to other descriptors like the device descriptor e.g. its `iProduct` field. + +✅ 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 diff --git a/embedded-workshop-book/src/getting-device-configured.md b/embedded-workshop-book/src/getting-device-configured.md index f93ac56..3de1585 100644 --- a/embedded-workshop-book/src/getting-device-configured.md +++ b/embedded-workshop-book/src/getting-device-configured.md @@ -23,7 +23,7 @@ The SET_CONFIGURATION request is sent by the host to configure the device. Its c - `wValue` contains the requested configuration value - `wIndex` and `wLength` are 0, there is no `wData` -To handle a SET_CONFIGURATION, do the following: +✅ 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. @@ -38,12 +38,15 @@ To handle a SET_CONFIGURATION, do the following: - if `wValue` is not valid then stall the endpoint In all the cases where you did not stall the endpoint (by returning `Err`) you'll need to acknowledge the request by starting a STATUS stage. -This is done by writing 1 to the TASKS_EP0STATUS register. + +✅ This is done by writing 1 to the TASKS_EP0STATUS register. NOTE: On Windows, you may get a `GET_STATUS` request *before* the `SET_CONFIGURATION` request and although you *should* respond to it, stalling the `GET_STATUS` request seems sufficient to get the device to the `Configured` state. ## Expected output +✅ Run the progam and check the log output. + Once you are correctly handling the `SET_CONFIGURATION` request you should get logs like these: ``` console diff --git a/embedded-workshop-book/src/inspecting-descriptors.md b/embedded-workshop-book/src/inspecting-descriptors.md index b894e2b..a26c839 100644 --- a/embedded-workshop-book/src/inspecting-descriptors.md +++ b/embedded-workshop-book/src/inspecting-descriptors.md @@ -1,9 +1,13 @@ # Inspecting the Descriptors -There's a tool in the `advanced/host/` folder called `print-descs`. You can run this tool to print all the descriptors reported by your application. +There's a tool in the `advanced/host/` folder called `print-descs`, it prints all the descriptors reported by your application. + +✅ Run this tool. + +Your output should look like this: ``` console -$ print-descs +$ cargo run DeviceDescriptor { bLength: 18, bDescriptorType: 1,