Update Documentation

.gitignore

@@ -0,0 +1,10 @@
+*.iws
+*.tmproj
+*.iml
+.idea
+.DS_Store
+_build
+_static/capabilities.zip
+.firebaserc
+database.rules.json
+firebase.json

.vscode/tasks.json

@@ -0,0 +1,26 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "build static site",
+            "type": "shell",
+            "command": "make clean html",
+            "problemMatcher": []
+        },
+        {
+            "label": "launch site",
+            "command": "Chrome",
+            "osx": {
+                "command": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+            },
+            "args": [
+                [
+                    "_build/html/index.html"
+                ]
+            ],
+            "problemMatcher": []
+        }
+    ]
+}

CONTRIBUTING.md

@@ -0,0 +1 @@
+Please see the [contributing guide](http://docs.smartthings.com/en/latest/contributing/style-guide.html "Writing the Docs") for formatting and syntax help when submitting changes to the documentation repository.

Makefile

@@ -2,10 +2,14 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
-BUILDDIR      = _build
+SPHINXOPTS            =
+SPHINXBUILD           = sphinx-build
+PAPER                 =
+BUILDDIR              = _build
+STATICDIR             = _static
+MKDIR_P               = mkdir -p
+CAPABILITIES_ZIP      = capabilities.zip
+CAPABILITIES_ZIP_URL  = https://smartthings-documentation.s3.amazonaws.com/$(CAPABILITIES_ZIP)
 
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)

README.md

@@ -0,0 +1,61 @@
+# SmartThings Developer Documentation
+
+This is the repository for the public SmartThings developer documentation.
+
+This documentation is written using [reStructuredText](http://docutils.sourceforge.net/rst.html), powered by [Sphinx](http://www.sphinx-doc.org/en/stable/), and hosted on [ReadTheDocs](http://readthedocs.org).
+
+## Building the docs
+
+Follow these steps to build the documentation locally:
+
+1. [Install virtualenv](https://virtualenv.pypa.io/en/latest/installation.html).
+2. Create an isolated environment in a different location than the Documentation directory: `virtualenv --no-site-packages .venv`
+3. Activate the environment: `source .venv/bin/activate`
+4. Install dependencies: `(.venv)~/Documentation$ pip install -r requirements.txt`
+5. Build HTML: `(.venv)~/Documentation$ make html`
+6. Open `_build/html/index.html` in a web browser.
+
+To see the available make targets, simply execute `make`.
+
+## Contributing
+
+We love contributions! If you find a typo, error, or think something can be communicated better, fork this repository and make a pull request.
+
+If you have a larger change that might involve a lot of new content or organization, let us know in advance by creating an issue.
+
+### Style guide
+For documentation formatting and syntax, please see the [Writing the Docs Guide](http://docs.smartthings.com/en/latest/contributing/style-guide.html).
+
+### Pull request guidelines
+
+We use the fork-and-pull GitHub flow.
+You should fork this repository, configure a remote for your fork, and keep your fork in sync.
+This is all documented in the [Working with forks](https://help.github.com/articles/working-with-forks) GitHub documentation.
+
+Once your fork is configured and synced with the latest, you should make your changes on a topic branch, commit those changes, and push the branch to make a Pull Request:
+
+1. Checkout a topic branch based off your master branch (this should be synced with the SmartThingsCommunity/Documentation repository):
+
+    `$ git checkout -b topic-branch-name origin/master`
+
+    Where "topic-branch-name" is descriptive of your changes (for example, "fix-scheduling-broken-link").
+
+2. Once you are confident in your changes, you can add them to your index and commit them. Be sure to include a meaningful commit message. Each PR should have exactly one commit. If you have multiple commits on your branch, squash them before making the PR.
+
+    **NOTE:** SmartThings employees should include the JIRA ticket number at the beginning of the commit message (e.g., "[DOCS-234] add documentation for passing data to scheduler method callbacks").
+
+3. Push your topic branch to your fork's remote:
+
+    `$ git push origin topic-branch-name`
+
+4. Visit your fork's remote in a web browser. There will be a yellow banner indicating new changes have been pushed, with the option to make a pull request from them. Click that link.
+
+5. On the Pull Request page, verify your changes look correct, add any description necessary, and submit the pull request. The documentation team will always review any pull requests, but if anything requires the attention of someone specific, `@` them in the pull request description.
+
+6. If there are changes requested as part of the pull request review, you can either add new commits to the PR, or amend your existing commit. If you add new commits, be sure to [squash them to one commit](https://github.com/ginatrapani/todo.txt-android/wiki/Squash-All-Commits-Related-to-a-Single-Issue-into-a-Single-Commit) before merging.
+
+7. Once the PR has a +1 (thumbs-up emoji), a member of the docs team will merge your PR.
+
+## Contact
+
+You can reach us at <mailto:docs@smartthings.com> with any feedback or questions.

_static/capabilities/acceleration-sensor.src/acceleration-sensor.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<capability name='Acceleration Sensor' public='true'>
+	<attribute name='acceleration' type='ENUM'>
+		<value name='active' />
+		<value name='inactive' />
+	</attribute>
+</capability>

_static/capabilities/acceleration-sensor.src/accelerationSensor.properties

@@ -0,0 +1,8 @@
+accelerationSensor.description=The Acceleration Sensor capability allows for acceleration detection. Some use cases for SmartApps using this capability would be detecting if a washing machine is vibrating, or if a case has moved (particularly useful for knowing if a weapon case has been moved).
+
+# Attributes
+accelerationSensor.attr.acceleration.description=A string representation of whether the sensor is active or not
+accelerationSensor.attr.acceleration.active.value=if acceleration is detected
+accelerationSensor.attr.acceleration.inactive.value=if no acceleration is detected
+
+# Commands

_static/capabilities/actuator.src/actuator.properties

@@ -0,0 +1,5 @@
+actuator.description=The Actuator capability is a "tagging" capability. It defines no attributes or commands. In SmartThings terms, it represents that a Device has commands.
+
+# Attributes
+
+# Commands

_static/capabilities/actuator.src/actuator.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<capability name='Actuator' public='true'/>

_static/capabilities/alarm.src/alarm.properties

@@ -0,0 +1,15 @@
+alarm.note=Z-Wave sometimes uses the term "Alarm" to refer to an important notification. The Alarm Capability is used in SmartThings to define a device that acts as an Alarm in the traditional sense (e.g., has a siren and such).
+alarm.description=The Alarm capability allows for interacting with devices that serve as alarms
+
+# Attributes
+alarm.attr.alarm.description=A string representation of whether the switch is on or off
+alarm.attr.alarm.both.value=if the alarm is strobing and sounding the alarm
+alarm.attr.alarm.off.value=if the alarm is turned off
+alarm.attr.alarm.siren.value=if the alarm is sounding the siren
+alarm.attr.alarm.strobe.value=if the alarm is strobing
+
+# Commands
+alarm.cmd.both.description=Strobe and sound the alarm
+alarm.cmd.off.description=Turn the alarm (siren and strobe) off
+alarm.cmd.siren.description=Sound the siren on the alarm
+alarm.cmd.strobe.description=Strobe the alarm

_static/capabilities/alarm.src/alarm.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<capability name='Alarm' public='true'>
+	<attribute name='alarm' type='ENUM'>
+		<value name='both' />
+		<value name='off' />
+		<value name='siren' />
+		<value name='strobe' />
+	</attribute>
+	<command name='both' />
+	<command name='off' />
+	<command name='siren' />
+	<command name='strobe' />
+</capability>

_static/capabilities/audio-notification.src/audio-notification.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+   <capability name='Audio Notification' public='true'>
+       <command name='playText'>
+           <argument name='message' type='STRING' />
+           <argument name='level' type='NUMBER' required="false"/>
+       </command>
+       <command name='playTextAndResume'>
+           <argument name='message' type='STRING' />
+           <argument name='level' type='NUMBER' required="false"/>
+       </command>
+       <command name='playTextAndRestore'>
+           <argument name='message' type='STRING' />
+           <argument name='level' type='NUMBER' required="false"/>
+       </command>
+       <command name='playTrack'>
+           <argument name='uri' type='STRING' />
+           <argument name='level' type='NUMBER' required="false"/>
+       </command>
+       <command name='playTrackAndResume'>
+           <argument name='uri' type='STRING' />
+           <argument name='level' type='NUMBER' required="false"/>
+       </command>
+       <command name='playTrackAndRestore'>
+           <argument name='uri' type='STRING' />
+           <argument name='level' type='NUMBER' required="false"/>
+       </command>
+   </capability>

_static/capabilities/audio-notification.src/audioNotification.properties

@@ -0,0 +1,23 @@
+audioNotification.description=Play a track or a message as an audio notification
+
+# Attributes
+
+# Commands
+audioNotification.cmd.playText.description=Play the given string
+audioNotification.cmd.playText.message.description=The text message to play
+audioNotification.cmd.playText.level.description=The volume at which to play the message
+audioNotification.cmd.playTextAndResume.description=Play the given message and resume playback of the previously playing track
+audioNotification.cmd.playTextAndResume.message.description=The text message to play
+audioNotification.cmd.playTextAndResume.level.description=The volume at which to play the message
+audioNotification.cmd.playTextAndRestore.description=Play the given message and restore the volume to its previous level
+audioNotification.cmd.playTextAndRestore.message.description=The text message to play
+audioNotification.cmd.playTextAndRestore.level.description=The volume at which to play the message
+audioNotification.cmd.playTrack.description=Play the given track
+audioNotification.cmd.playTrack.uri.description=The URI of the track to be played
+audioNotification.cmd.playTrack.level.description=The volume at which to play the track
+audioNotification.cmd.playTrackAndResume.description=Play the given track and resume playback of the previously playing track
+audioNotification.cmd.playTrackAndResume.uri.description=The URI of the track to be played
+audioNotification.cmd.playTrackAndResume.level.description=The volume at which to play the track
+audioNotification.cmd.playTrackAndRestore.description=Play the given track and restore the volume to its previous level
+audioNotification.cmd.playTrackAndRestore.uri.description=The URI of the track to be played
+audioNotification.cmd.playTrackAndRestore.level.description=The volume at which to play the track

_static/capabilities/battery.src/battery.properties

@@ -0,0 +1,6 @@
+battery.description=Defines that the device has a battery
+
+# Attributes
+battery.attr.battery.description=An indication of the status of the battery
+
+# Commands

_static/capabilities/battery.src/battery.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<capability name='Battery' public='true'>
+	<attribute name='battery' type='NUMBER' unit='%' />
+</capability>

_static/capabilities/beacon.src/beacon.properties

@@ -0,0 +1,8 @@
+beacon.description=Detect whether or not the beacon is present
+
+# Attributes
+beacon.attr.presence.description=The presence value of the beacon
+beacon.attr.presence.not present.value=Value when beacon is not present
+beacon.attr.presence.present.value=Value when beacon is present
+
+# Commands

_static/capabilities/beacon.src/beacon.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<capability name='Beacon' public='true'>
+	<attribute name='presence' type='ENUM'>
+		<value name='not present' />
+		<value name='present' />
+	</attribute>
+</capability>

_static/capabilities/bridge.src/bridge.properties

@@ -0,0 +1,6 @@
+bridge.description=The Bridge capability is a "tagging" capability. It defines no attributes or commands. In SmartThings terms, it represents that a Device is a bridge to other devices.
+
+
+# Attributes
+
+# Commands

_static/capabilities/bridge.src/bridge.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<capability name='Bridge' public='true'/>

_static/capabilities/bulb.src/bulb.properties

@@ -0,0 +1,10 @@
+bulb.description=Allows for the control of a bulb device
+
+# Attributes
+bulb.attr.switch.description=A string representation of whether the bulb is on or off
+bulb.attr.switch.on.value=The value of the ``switch`` attribute if the bulb is on
+bulb.attr.switch.off.value=The value of the ``switch`` attribute if the bulb is off
+
+# Commands
+bulb.cmd.on.description=Turn a bulb on
+bulb.cmd.off.description=Turn a bulb off

_static/capabilities/bulb.src/bulb.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<capability name='Bulb' public='true'>
+	<attribute name='switch' type='ENUM'>
+		<value name='off' />
+		<value name='on' />
+	</attribute>
+	<command name='off' />
+	<command name='on' />
+</capability>

_static/capabilities/button.src/button.properties

@@ -0,0 +1,9 @@
+button.description=A device with one or more buttons
+
+# Attributes
+button.attr.button.description=The state of the button
+button.attr.button.pushed.value=The value if the button is pushed
+button.attr.button.held.value=The value if the button is held
+button.attr.numberOfButtons.description=The number of buttons on the device
+
+# Commands

_static/capabilities/button.src/button.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<capability name='Button' public='true'>
+	<attribute name='button' type='ENUM'>
+		<value name='pushed' />
+		<value name='held' />
+	</attribute>
+	<attribute name='numberOfButtons' type='NUMBER' />
+</capability>

_static/capabilities/carbon-dioxide-measurement.src/carbon-dioxide-measurement.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<capability name='Carbon Dioxide Measurement' public='true'>
+	<attribute name='carbonDioxide' type='NUMBER' />
+</capability>

_static/capabilities/carbon-dioxide-measurement.src/carbonDioxideMeasurement.properties

@@ -0,0 +1,6 @@
+carbonDioxideMeasurement.description=Measure carbon dioxide levels
+
+# Attributes
+carbonDioxideMeasurement.attr.carbonDioxide.description=The level of carbon dioxide detected
+
+# Commands

_static/capabilities/carbon-monoxide-detector.src/carbon-monoxide-detector.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<capability name='Carbon Monoxide Detector' public='true'>
+	<attribute name='carbonMonoxide' type='ENUM'>
+		<value name='clear' />
+		<value name='detected' />
+		<value name='tested' />
+	</attribute>
+</capability>

_static/capabilities/carbon-monoxide-detector.src/carbonMonoxideDetector.properties

@@ -0,0 +1,9 @@
+carbonMonoxideDetector.description=Measure carbon monoxide levels
+
+# Attributes
+carbonMonoxideDetector.attr.carbonMonoxide.description=The state of the carbon monoxide device
+carbonMonoxideDetector.attr.carbonMonoxide.clear.value=No carbon monoxide detected
+carbonMonoxideDetector.attr.carbonMonoxide.detected.value=Carbon monoxide detected
+carbonMonoxideDetector.attr.carbonMonoxide.tested.value=Carbon monoxide device test button was activated
+
+# Commands

_static/capabilities/color-control.src/color-control.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<capability name='Color Control' public='true'>
+	<attribute name='color' type='STRING' />
+	<attribute name='hue' type='NUMBER' />
+	<attribute name='saturation' type='NUMBER' />
+	<command name='setColor'>
+		<argument name='color' type='COLOR_MAP'>
+			<component name='hue' type='NUMBER'/>
+			<component name='saturation' type='NUMBER'/>
+		</argument>
+	</command>
+	<command name='setHue'>
+		<argument name='hue' type='NUMBER' />
+	</command>
+	<command name='setSaturation'>
+		<argument name='saturation' type='NUMBER' />
+	</command>
+</capability>

_static/capabilities/color-control.src/colorControl.properties

@@ -0,0 +1,16 @@
+colorControl.description=Allows for control of a color changing device by setting its hue, saturation, and color values
+
+# Attributes
+colorControl.attr.color.description=``{"hue":"0-100 (percent)", "saturation":"0-100 (percent)"}``
+colorControl.attr.hue.description=``0-100`` (percent)
+colorControl.attr.saturation.description=``0-100`` (percent)
+
+# Commands
+colorControl.cmd.setColor.description=Sets the color based on the values passed in with the given map
+colorControl.cmd.setColor.color.description=The color map supports the following key/value pairs:
+colorControl.cmd.setColor.color.hue.value=The desired hue value
+colorControl.cmd.setColor.color.saturation.value=The desired saturation value
+colorControl.cmd.setHue.description=Set the hue value of the color
+colorControl.cmd.setHue.hue.description=A number in the range ``0-100`` representing the hue as a value of percent
+colorControl.cmd.setSaturation.description=Set the saturation value of the color
+colorControl.cmd.setSaturation.saturation.description=A number in the range ``0-100`` representing the saturation as a value of percent

_static/capabilities/color-temperature.src/color-temperature.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<capability name='Color Temperature' public='true'>
+	<attribute name='colorTemperature' type='NUMBER' />
+	<command name='setColorTemperature'>
+		<argument name='temperature' type='NUMBER' />
+	</command>
+</capability>

_static/capabilities/color-temperature.src/colorTemperature.properties

@@ -0,0 +1,8 @@
+colorTemperature.description=Set the color temperature attribute of a color changing device
+
+# Attributes
+colorTemperature.attr.colorTemperature.description=A number that represents the color temperature, measured in degrees Kelvin
+
+# Commands
+colorTemperature.cmd.setColorTemperature.description=Set the color temperature to the specified value
+colorTemperature.cmd.setColorTemperature.temperature.description=The value to set the color temperature attribute to, in Kelvin