blob: 1f5cc46776f61497193e81d589b6d97778530a66 [file] [log] [blame]
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:
cros_workon-${BOARD} start buffet
# Edit files in platform2/buffet/
vim ...
# Compile and install those changes into the chroot:
USE=buffet emerge-${BOARD} buffet
# Compile and run buffet unittests
USE=buffet FEATURES=test emerge-${BOARD} buffet
# Deploy the most recently built version of buffet to a DUT:
cros deploy --board=${BOARD} <remote host> buffet
#To enable additional debug logging in buffet daemon, run it as:
# buffet --v=<level>, where <level> is verbosity level of debug info:
# 1 - enable additional tracing of internal object construction and destruction
# 2 - add tracing of request and response data sent over HTTP (beware of
# 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.