buffet: Add instructions for registering a DUT. This took me quite a while to get right and I imagine this will be true for most people starting to work on the project. These notes should make the process a lot easier. TEST=Followed the steps and registering a DUT worked. BUG=brillo:238 Change-Id: I40f420b4a4484e2468cbb4b1dd62d285494611c2 Reviewed-on: https://chromium-review.googlesource.com/250420 Reviewed-by: Anton Muhin <antonm@chromium.org> Commit-Queue: David Zeuthen <zeuthen@chromium.org> Tested-by: David Zeuthen <zeuthen@chromium.org>
diff --git a/buffet/HACKING b/buffet/HACKING index fcfc08c..95c6193 100644 --- a/buffet/HACKING +++ b/buffet/HACKING
@@ -1,3 +1,12 @@ +This file is intended for onboarding new SWEs hacking on buffet. + + A. Common workflows. + B. Registering your DUT. + +--- +A. COMMON WORKFLOWS +--- + Some common workflows for developing with buffet: # Tell portage that you'd like to make local changes to Buffet: @@ -22,3 +31,117 @@ # privacy concerns). # 3 - enable low-level CURL tracing for HTTP communication. buffet --v=2 + +--- +B. REGISTERING YOUR DUT +--- + +This process in described in great detail at + + https://developers.google.com/cloud-devices/v1/dev-guides/getting-started/register + +but since these instructions are generic and comprehensive, here's +exactly what you need to do to get started when working with +buffet/Brillo, in ten simple steps. + +The word DUT in this context is meant as the device that you want to +associate with the cloud - for most buffet/Brillo developers this will +be a Chromebook or another embedded device. These notes assume you +have shell access to the DUT and also have access to a normal Linux +workstation with shell and browser access. + +1. Open an Incognito window in Chrome on your workstation, go to +https://www.google.com and log in with your test google account (NEVER +use @google.com credentials on DUTs). In the following we're using +<GMAIL_TEST_ACCOUNT> which you should replace with whatever you're +using, e.g. my-testing-account-xyz@gmail.com. + +2. First we need an Authorization Code for the test user. This is +covered in more detail in + + https://developers.google.com/cloud-devices/v1/dev-guides/getting-started/authorizing#code + +but basically amounts to entering the following URL in the Incognito window + + https://accounts.google.com/o/oauth2/auth?scope=https://www.googleapis.com/auth/clouddevices&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code&client_id=58855907228.apps.googleusercontent.com + +If you're not using the default buffet gcd-project, replace the +client_id parameter in the URL with the one for the product you +registered as per + + https://developers.google.com/cloud-devices/v1/dev-guides/getting-started/authorizing#setup + +3. The browser window should display a prompt saying that +"clouddevicesclient" would like to "Manage your cloud device". Press +the "Accept" button and write down the Authorization Code +displayed. It should look something like this + + 4/J23qfSkXYFgF_0H7DCOtwS5O7HO69zF9LtnG9_ILIGA.QhJE9WLeqwcaJvIeHux6iLavlvowlwI + +4. Open a bash prompt on your Linux workstation and type the following + + export SETUP_USER=<GMAIL_TEST_ACCOUNT> + export SETUP_CODE=4/J23qfSkXYFgF_0H7DCOtwS5O7HO69zF9LtnG9_ILIGA.QhJE9WLeqwcaJvIeHux6iLavlvowlwI + export SETUP_CLIENT_ID=58855907228.apps.googleusercontent.com + export SETUP_CLIENT_SECRET=eHSAREAHrIqPsHBxCE9zPPBi + +replacing the values for SETUP_USER and SETUP_CODE as +appropriate. Again, if you're not using the default buffet gcd-project +replace the values SETUP_CLIENT_ID and SETUP_CLIENT_SECRET as +appropriate. + +5. Now we can get an Access Token. Run the following command from the shell: + + curl -d "code=${SETUP_CODE}&client_id=${SETUP_CLIENT_ID}&client_secret=${SETUP_CLIENT_SECRET}&redirect_uri=urn:ietf:wg:oauth:2.0:oob&grant_type=authorization_code" https://accounts.google.com/o/oauth2/token + +It should print out something like this: + + { + "access_token" : "ya29.HQE<...>", + "token_type" : "Bearer", + "expires_in" : 3600, + "refresh_token" : "1/iMq4<...>" + } + +6. Export the access token in the shell: + + export SETUP_ACCESS_TOKEN=ya29.HQE<...> + +7. Now we can get the Registration Ticket Id for the device. Run the following + + curl --header "Authorization: Bearer ${SETUP_ACCESS_TOKEN}" --header "Content-Type: application/json; charset=UTF-8" --data "{ \"userEmail\": \"${SETUP_USER}\" }" https://www.googleapis.com/clouddevices/v1/registrationTickets + +It should print out something like this + + { + "kind": "clouddevices#registrationTicket", + "id": "453f1139-bd<...>", + "deviceId": "77500a3f-458b-<...>", + "userEmail": "<GMAIL_TEST_ACCOUNT>", + "creationTimeMs": "1424193538212", + "expirationTimeMs": "1424193778212" + } + +8. Now, open a shell on the DUT and export the following + + export DUT_SETUP_TICKET_ID=453f1139-bd<...> + +9. Run the following command on the DUT shell + + buffet_client RegisterDevice ticket_id=${DUT_SETUP_TICKET_ID} + +appropriate. If you're not using the default buffet gcd-project you +also need to pass other parameters such as client_id, client_secret +and api_key. + +It should succeed and print the device-id + + Device registered: 77500a3f-458b-<...> + +10. The registered DUT should now show up in the Google account that +you associated it with. In the Incognito window opened in step 1, go +to + + https://security.google.com/settings/security/permissions + +where you can e.g. revoke access to the device.