Interact with the Nest API quickly and easily on Android.
Sample Android app: https://github.com/nestlabs/android-sdk-sample
Javadocs: https://nestlabs.github.io/android-sdk/
Examples are also available in this README below.
Add the following line to your build.gradle
in your Android project:
compile 'com.nestlabs:android-sdk:1.0.0'
Setup your Nest instance, preparing it for Authorization / Authentication.
// Set your Context (required - only once)
NestAPI.setAndroidContext(context);
// Get your Nest API instance.
NestAPI nest = NestAPI.getInstance();
Before we can get started making requests to the Nest API, we must first get authorization from the user. This authorization is in the form of an access token.
We must launch an OAuth 2.0 flow in order to get an access token initially. Then later, we can re-use that token.
// A request code you can verify later.
int AUTH_TOKEN_REQUEST_CODE = 123;
// Set the configuration values.
nest.setConfig("client-id", "client-secret", "https://redirect-url");
// Launch the auth flow if you don't already have a token.
nest.launchAuthFlow(getActivity(), AUTH_TOKEN_REQUEST_CODE);
// On your Activity, override the following method to receive the token:
@Override
public void onActivityResult(int requestCode, int resultCode, Intent intent) {
if (resultCode != RESULT_OK || requestCode != AUTH_TOKEN_REQUEST_CODE) {
return; // No token will be available.
}
NestToken token = NestAPI.getAccessTokenFromIntent(intent);
// Save the token to a safe place here so it can be re-used later.
}
If you already have an access token, you can authenticate using that immediately.
// Get existing instance.
NestAPI nest = NestAPI.getInstance();
// Get the token string from your safe place.
String token = "abc123";
// or...
// Get the NestToken object (it's Parcelable!)
NestToken token = getMyToken();
// Authenticate with an existing token.
nest.authWithToken(token, new NestAuthListener() {
@Override
public void onAuthSuccess() {
// Handle success here. Start pulling from Nest API.
}
@Override
public void onAuthFailure(NestException e) {
// Handle exceptions here.
}
@Override
public void onAuthRevoked() {
// Your previously authenticated connection has become unauthenticated.
// Recommendation: Relaunch an auth flow with nest.launchAuthFlow().
}
});
This includes all devices, structures and metadata.
nest.addGlobalListener(new GlobalListener() {
@Override
public void onUpdate(@NonNull GlobalUpdate update) {
Metadata metadata = update.getMetadata();
ArrayList<Camera> cameras = update.getCameras();
ArrayList<SmokeCOAlarm> thermostats = update.getSmokeCOAlarms();
ArrayList<Thermostat> thermostats = update.getThermostats();
ArrayList<Structure> structures = update.getStructures();
// Handle updates here.
}
});
This includes all thermostats, smoke alarms and cameras.
nest.addDeviceListener(new DeviceListener() {
@Override
public void onUpdate(@NonNull NestDeviceUpdate update) {
ArrayList<Camera> cameras = update.getCameras();
ArrayList<SmokeCOAlarm> thermostats = update.getSmokeCOAlarms();
ArrayList<Thermostat> thermostats = update.getThermostats();
// Handle updates here.
}
});
nest.addThermostatListener(new ThermostatListener() {
@Override
public void onUpdate(@NonNull ArrayList<Thermostat> thermostats) {
// Handle thermostat update...
}
});
nest.addSmokeCOAlarmListener(new SmokeCOAlarmListener() {
@Override
public void onUpdate(@NonNull ArrayList<SmokeCOAlarm> alarms) {
// Handle smoke+co alarm update...
}
});
nest.addCameraListener(new CameraListener() {
@Override
public void onUpdate(@NonNull ArrayList<Camera> cameras) {
// Handle camera update...
}
});
nest.addStructureListener(new StructureListener() {
@Override
public void onUpdate(@NonNull ArrayList<Structure> structures) {
// Handle structure update...
}
});
This includes the access token and client version.
nest.addMetadataListener(new MetadataListener() {
@Override
public void onUpdate(Metadata data) {
// Handle metadata update... do action.
}
});
Remove a specific listener.
nest.removeListener(listener); // Removes a specific listener.
Remove all listeners.
nest.removeAllListeners(); // Removes all listeners.
Updating values on devices and structures is easy. Here are a few examples.
See the full list of possible Thermostat methods here.
// Get id from Thermostat#getDeviceId
String thermostatId = myThermostat.getDeviceId();
// The temperature in Farhenheit to set. (Note: type long)
long newTemp = 75;
// Set thermostat target temp (in degrees F).
nest.thermostats.setTargetTemperatureF(thermostatId, newTemp);
See the full list of possible Thermostat methods here.
// Get id from Thermostat#getDeviceId
String thermostatId = myThermostat.getDeviceId();
// The temperature in Celsius to set. (Note: type double)
double newTemp = 22.5;
// Set thermostat target temp (in degrees C) with an optional success callback.
nest.thermostats.setTargetTemperatureC(thermostatId, newTemp, new Callback() {
@Override
public void onSuccess() {
// The update to the thermostat succeeded.
}
@Override
public void onFailure(NestException e) {
// The update to the thermostat failed.
}
});
See the full list of possible Camera methods here.
// Get id from Camera#getDeviceId.
String camId = myCamera.getDeviceId();
// Set camera to start streaming.
nest.cameras.setIsStreaming(camId, true);
See the full list of possible Camera methods here.
// Get id from Camera#getDeviceId.
String camId = myCamera.getDeviceId();
// Set camera to start streaming with an optional success callback.
nest.cameras.setIsStreaming(camId, true, new Callback() {
@Override
public void onSuccess() {
// The update to the camera succeeded.
}
@Override
public void onFailure(NestException e) {
// The update to the camera failed.
}
});
Contributions are always welcome and highly encouraged.
See CONTRIBUTING for more information on how to get started.
Apache 2.0 - See LICENSE for more information.