{"_id":"571826e0951a050e0064564b","__v":82,"version":{"_id":"56130e2ad2b2370d0096b91d","project":"56130e29d2b2370d0096b91a","__v":11,"createdAt":"2015-10-05T23:56:26.509Z","releaseDate":"2015-10-05T23:56:26.509Z","categories":["56130e2bd2b2370d0096b91e","56130f638e503f0d00648b05","561317cdbe80130d00f188dd","561317d8ff92880d005ca212","56f97c0f8fef7520003f818e","570d751180c9010e00d77f4d","570d7543e2a0b40e0077aa90","571699927256fb0e00c1d01c","57f43db31592cb0e00761dd6","57f52ed668a53b2000e03efa","57f5350f485e6e2b005b2f27"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"0.0.0","version":"0"},"category":{"_id":"56130e2bd2b2370d0096b91e","version":"56130e2ad2b2370d0096b91d","pages":["56130e2bd2b2370d0096b920","56130f838e503f0d00648b06"],"project":"56130e29d2b2370d0096b91a","__v":2,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-10-05T23:56:27.097Z","from_sync":false,"order":0,"slug":"documentation","title":"Documentation"},"project":"56130e29d2b2370d0096b91a","user":"56130dcf8e503f0d00648b03","parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-04-21T01:03:28.387Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"This tutorial will get you started with lighting controls.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Getting the Access Token\"\n}\n[/block]\nPosting a user's email address and password to the [OAuth 2.0 endpoint](http://developers.stacklighting.com/docs/oauth-20) will return the user's *access_token*.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST 'https://api.stacklighting.com/v0/oauth2/token' \\\\\\n     -H 'Content-Type: application/json' \\\\\\n     -d '{\\\"grant_type\\\":\\\"password\\\", \\\"client_id\\\":\\\"98f59d7a9d6379ed812e2b2444f87e89\\\", \\\"email\\\":\\\"darth:::at:::stacklighting.com\\\",\\\"password\\\":\\\"deathstar4eva\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Getting Sites\"\n}\n[/block]\nAll subsequent calls will require the user's *access_token* in the header. [GET Sites](http://developers.stacklighting.com/docs/sites) to obtain a list of all of a user's sites.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET 'https://api.stacklighting.com/v0/sites' \\\\\\n     -H 'Content-Type: application/json' \\\\\\n     -H 'Authorization: Bearer YmE3MTU5MWItZTIwMC00MDc2LWJmZTQtZDH5YmUxMTA0ZTNmOjU3NjE2NzM5MzE1MjIwNDg='\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Getting Zones\"\n}\n[/block]\n[GET Zones](http://developers.stacklighting.com/docs/zones) to obtain a list of zones for a *site_id*.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET 'https://api.stacklighting.com/v0/sites/6133345811384985/zones' \\\\\\n     -H 'Content-Type: application/json' \\\\\\n     -H 'Authorization: Bearer YmE3MTU5MWItZTIwMC00MDc2LWJmZTQtZDH5YmUxMTA0ZTNmOjU3NjE2NzM5MzE1MjIwNDg='\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Updating Zone Settings\"\n}\n[/block]\n[PUT Zone Settings](http://developers.stacklighting.com/docs/zone-settings) with the *zone_id* for the zone whose settings you'd like to update. In the example below, a zone is updated to maximum brightness. Voilà!\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X PUT 'https://api.stacklighting.com/v0/sites/6133345811384985/zones/6022860457570431/settings' \\\\\\n     -H 'Content-Type: application/json' \\\\\\n     -H 'Authorization: Bearer YmE3MTU5MWItZTIwMC00MDc2LWJmZTQtZDH5YmUxMTA0ZTNmOjU3NjE2NzM5MzE1MjIwNDg=' \\\\\\n     -d '{\\\"brightness\\\":2000}' \",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"A Note on Lighting Modes\"\n}\n[/block]\nStack supports several zone lighting modes, including *auto*, *manual*, *schedule* and *sleep*. We'll be opening up additional access to control these modes over time. Some things to note:\n* *auto* refers to a state in which zones receive periodic updates to brightness and color that are determined by Stack's Circadian Lighting schedule, machine learning around a user's unique preferences, and ambient light sensing (ALS).\n* ALS, which can be toggled with the *als_adjust_on* property, can only be enabled when a zone is in *auto*. Bulbs with ALS enabled will dim until they reach the *als_adjust_floor*. Each bulb will dim independently of other bulbs in its zone.\n* Motion properties like *motion_timeout_on* and *motion_timeout_seconds* can be adjusted regardless of mode.\n* Changing a zone's *brightness* or *color* properties will put that zone into *manual*.\n* We do not currently expose an endpoint to set a zone to *auto*, but we plan to release one in the coming weeks. Until then, users can set a zone to Auto in that zone's Controls tab in the Stack Lighting app and configure whether or not a zone in *manual* should \"Return to Auto\" automatically after a given period without motion in that zone's Settings tab under Auto Mode.","excerpt":"","slug":"lighting-controls","type":"basic","title":"Lighting Controls 💡"}

Lighting Controls 💡


This tutorial will get you started with lighting controls. [block:api-header] { "type": "basic", "title": "Getting the Access Token" } [/block] Posting a user's email address and password to the [OAuth 2.0 endpoint](http://developers.stacklighting.com/docs/oauth-20) will return the user's *access_token*. [block:code] { "codes": [ { "code": "curl -X POST 'https://api.stacklighting.com/v0/oauth2/token' \\\n -H 'Content-Type: application/json' \\\n -d '{\"grant_type\":\"password\", \"client_id\":\"98f59d7a9d6379ed812e2b2444f87e89\", \"email\":\"darth@stacklighting.com\",\"password\":\"deathstar4eva\"}'", "language": "curl" } ] } [/block] [block:api-header] { "type": "basic", "title": "Getting Sites" } [/block] All subsequent calls will require the user's *access_token* in the header. [GET Sites](http://developers.stacklighting.com/docs/sites) to obtain a list of all of a user's sites. [block:code] { "codes": [ { "code": "curl -X GET 'https://api.stacklighting.com/v0/sites' \\\n -H 'Content-Type: application/json' \\\n -H 'Authorization: Bearer YmE3MTU5MWItZTIwMC00MDc2LWJmZTQtZDH5YmUxMTA0ZTNmOjU3NjE2NzM5MzE1MjIwNDg='", "language": "curl" } ] } [/block] [block:api-header] { "type": "basic", "title": "Getting Zones" } [/block] [GET Zones](http://developers.stacklighting.com/docs/zones) to obtain a list of zones for a *site_id*. [block:code] { "codes": [ { "code": "curl -X GET 'https://api.stacklighting.com/v0/sites/6133345811384985/zones' \\\n -H 'Content-Type: application/json' \\\n -H 'Authorization: Bearer YmE3MTU5MWItZTIwMC00MDc2LWJmZTQtZDH5YmUxMTA0ZTNmOjU3NjE2NzM5MzE1MjIwNDg='", "language": "curl" } ] } [/block] [block:api-header] { "type": "basic", "title": "Updating Zone Settings" } [/block] [PUT Zone Settings](http://developers.stacklighting.com/docs/zone-settings) with the *zone_id* for the zone whose settings you'd like to update. In the example below, a zone is updated to maximum brightness. Voilà! [block:code] { "codes": [ { "code": "curl -X PUT 'https://api.stacklighting.com/v0/sites/6133345811384985/zones/6022860457570431/settings' \\\n -H 'Content-Type: application/json' \\\n -H 'Authorization: Bearer YmE3MTU5MWItZTIwMC00MDc2LWJmZTQtZDH5YmUxMTA0ZTNmOjU3NjE2NzM5MzE1MjIwNDg=' \\\n -d '{\"brightness\":2000}' ", "language": "curl" } ] } [/block] [block:api-header] { "type": "basic", "title": "A Note on Lighting Modes" } [/block] Stack supports several zone lighting modes, including *auto*, *manual*, *schedule* and *sleep*. We'll be opening up additional access to control these modes over time. Some things to note: * *auto* refers to a state in which zones receive periodic updates to brightness and color that are determined by Stack's Circadian Lighting schedule, machine learning around a user's unique preferences, and ambient light sensing (ALS). * ALS, which can be toggled with the *als_adjust_on* property, can only be enabled when a zone is in *auto*. Bulbs with ALS enabled will dim until they reach the *als_adjust_floor*. Each bulb will dim independently of other bulbs in its zone. * Motion properties like *motion_timeout_on* and *motion_timeout_seconds* can be adjusted regardless of mode. * Changing a zone's *brightness* or *color* properties will put that zone into *manual*. * We do not currently expose an endpoint to set a zone to *auto*, but we plan to release one in the coming weeks. Until then, users can set a zone to Auto in that zone's Controls tab in the Stack Lighting app and configure whether or not a zone in *manual* should "Return to Auto" automatically after a given period without motion in that zone's Settings tab under Auto Mode.