node-hue-api/docs/schedules.md

Philips Hue API Library for Node.js

# Schedules API

The `schedules` API provides a means of interacting with the `Schedule`s in the Hue Bridge.

The Schedules API interacts with [`Schedule`](./schedule.md) objects along with their associated 
[Time Patterns](./timePatterns.md).


* [getAll()](#getall)
* [getSchedule(id)](#getschedule)
* [getScheduleByName(name)](#getschedulebyname)
* [createSchedule()](#createschedule)
* [updateSchedule()](#updateschedule)
* [deleteSchedule()](#deleteschedule)


## getAll()
The `getAll()` function allows you to get all the `Schedule`s that the Hue Bridge has registered with it.

```js
api.schedules.getAll()
  .then(allSchedules => {
    // Display the Schedules from the bridge
    allSchedules.forEach(schedule => {
      console.log(schedule.toStringDetailed());
    });
  });
```

This function call will resolve to an `Array` of `Schedule` objects. 

A complete code sample for this function is available [here](../examples/v3/schedules/getAllSchedules.js).



## getSchedule()
The `getSchedule(id)` function allows a specific `Schedule` to be retrieved from the Hue Bridge.

* `id`: The `id` of the `Schedule` or a `Schedule` instance that was previously obtained from the bridge.


```js
api.schedules.getSchedule(1)
  .then(schedule => {
    console.log(schedule.toStringDetailed());
  })
;
```

This function call will resolve to a `Schedule` object for the specified schedule `id`.

If the Scene cannot be found an `ApiError` will be returned with a `getHueErrorType()` value of `3`.

A complete code sample for this function is available [here](../examples/v3/schedules/getScheduleById.js).



## getScheduleByName()
The `getScheduleByName(name)` function will find all the `Schedule`s that are stored in the bridge with the specified `name`.

* `name`: The `String` that represents the name of the `Schedules`s that you wish to find.

```js
api.schedules.getScheduleByName('Wake Up')
  .then(results => {
    // Do something with the schedules we matched
    results.forEach(scene => {
      console.log(schedule.toStringDetailed());
    });
  })
;
```

The function will resolve to an `Array` of `Schedule` Objects that were matched to the specified `name`. It none are
matched the `Array` will be empty.

A complete code sample for this function is available [here](../examples/v3/schedules/getSchedulesByName.js).



## createSchedule()
The `createSchedule(schedule)` function allows for the creation of new `Schedule`s in the Hue Bridge.

* `schedule`: A `Schedule` object that has been configured with the desired settings for the `Schedule` being created.

```js
const model = require('node-hue-api').v3.model;

const schedule = model.createSchedule();
schedule.name = 'My Schedule';
schedule.description = 'A test schedule from the node-hue-api examples';
// trigger the schedule in 1 hour from now
schedule.localtime = model.timePatterns.createTimer().hours(1);
// Turn all the lights off (using light group 0 for all lights)
schedule.command = model.actions.group(0).withState(new model.lightStates.GroupLightState().off());

api.schedules.createSchedule(schedule)
  .then(createdSchedule => {
    console.log(`Successfully created Schedule\n${createdSchedule.toStringDetailed()}`);
  })
;
```

The function will return a Promise that will resolve with a corresponding `Schedule` with a populated `id` attribute.

A complete code sample for this function is available [here](../examples/v3/schedules/createSchedule.js).



## updateSchedule()
The `updateSchedule(schedule)` function will update the schedule in the bridge to match the attributes of the specified 
schedule.

* `schedule`: The schedule with updated attributes to set on the bridge. 

```js
// Obtain a schedule from the Bridge, e.g. get schedule with id = 1
const mySchedule = await hue.schedules.get(1);

// Update some attributes
mySchedule.name = 'Updated Name';

// Update the schedule in the bridge
hue.schedules.updateSchedule(mySchedule)
  .then(updateResult => {
    console.log(`Updated Name? ${updateResult.name}`); // Will print "Updated Name? true" 
  });
```

_Note: Currently there is no checking as to whether or not a value has been modified, so all the updatable attributes are
passed to the bridge. (this is quicker and more efficient than doing a get/put chain of requests)._

The function call will return a `Promise` that will resolve to an `Object` with the update information.

The result Object that will have the form of the keys that were updated along with a boolean flag 
indicating if the value was modified.
```js
{
  "name": true,
  "description": true,
  "command": true,
  "localtime": true,
  "status": true,
  "autodelete": true
}
```

A complete code sample for this function is available [here](../examples/v3/schedules/updateSchedule.js).



## deleteSchedule()
The `deleteSchedule(id)` function will delete the specified scene identified by the `id` from the Hue Bridge.

* `id`: The `id` of the scene to delete from the Hue Bridge.

```js
api.scenes.delete('abc170f')
  .then(result => {
    console.log(`Deleted scene? ${result}`);
  })
;
```

The call will resolve to a `Boolean` indicating the success status of the deletion.

A complete code sample for this function is available [here](../examples/v3/scenes/deleteScene.js).