From a43892d5581d9bf9e4e405a035617ebf0da8513d Mon Sep 17 00:00:00 2001 From: Raj Karamchedu Date: Tue, 14 Mar 2017 09:40:31 -0700 Subject: [PATCH] [DOCS-463] Revised docs to update glossary terms (#597) * Fixing glossary terms * Revised corrections --- .gitignore | 3 + architecture/index.rst | 44 +++++----- arduino/index.rst | 6 +- .../building-the-device-type.rst | 30 +++---- .../division-of-labor.rst | 8 +- .../index.rst | 8 +- .../building-the-device-type.rst | 18 ++-- .../building-the-service-manager.rst | 36 ++++---- .../division-of-labor.rst | 4 +- .../index.rst | 10 +-- .../index.rst | 6 +- ...e-manage-device-handler-design-pattern.rst | 18 ++-- code-review-guidelines.rst | 10 +-- .../building-z-wave-device-handlers.rst | 18 ++-- .../building-zigbee-device-handlers.rst | 8 +- .../definition-metadata.rst | 2 +- .../device-integration.rst | 8 +- .../device-preferences.rst | 4 +- device-type-developers-guide/index.rst | 4 +- device-type-developers-guide/overview.rst | 22 ++--- device-type-developers-guide/parse.rst | 32 +++---- device-type-developers-guide/quick-start.rst | 16 ++-- .../simulator-metadata.rst | 22 ++--- .../tiles-metadata.rst | 6 +- .../z-wave-primer.rst | 4 +- .../zigbee-primer.rst | 4 +- getting-started/first-smartapp.rst | 68 +++++++-------- getting-started/overview.rst | 4 +- getting-started/up-and-running.rst | 4 +- latest-updates.rst | 2 +- ratelimits/index.rst | 4 +- ref-docs/app-state-ref.rst | 26 +++--- ref-docs/async-response-ref.rst | 2 +- ref-docs/device-handler-ref.rst | 52 ++++++------ ref-docs/device-ref.rst | 12 +-- ref-docs/event-ref.rst | 42 +++++----- ref-docs/hub-ref.rst | 2 +- ref-docs/hubaction-ref.rst | 12 +-- ref-docs/location-ref.rst | 30 +++---- ref-docs/mode-ref.rst | 4 +- ref-docs/reference.rst | 2 +- ref-docs/smartapp-ref.rst | 84 +++++++++---------- sept-2015-faq.rst | 10 +-- .../anatomy-and-life-cycle-of-a-smartapp.rst | 28 +++---- smartapp-developers-guide/devices.rst | 6 +- .../example-bon-voyage.rst | 20 ++--- smartapp-developers-guide/modes.rst | 12 +-- .../parent-child-smartapps.rst | 6 +- .../preferences-and-settings.rst | 16 ++-- smartapp-developers-guide/routines.rst | 4 +- smartapp-developers-guide/scheduling.rst | 2 +- .../sending-notifications.rst | 12 +-- .../simple-event-handler-smartapps.rst | 30 +++---- smartapp-developers-guide/state.rst | 2 +- .../sunset-and-sunrise.rst | 36 ++++---- smartapp-developers-guide/time-methods.rst | 4 +- .../troubleshooting.rst | 8 +- .../tutorial-part1.rst | 24 +++--- .../tutorial-part2.rst | 4 +- tools-and-ide/account-mgmt.rst | 8 +- tools-and-ide/editor-and-simulator.rst | 2 +- tools-and-ide/github-integration.rst | 10 +-- 62 files changed, 474 insertions(+), 471 deletions(-) diff --git a/.gitignore b/.gitignore index 0aa9fbfa..8f5cb10a 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,6 @@ .DS_Store _build _static/capabilities.zip +.firebaserc +database.rules.json +firebase.json diff --git a/architecture/index.rst b/architecture/index.rst index ae75f728..5205178e 100644 --- a/architecture/index.rst +++ b/architecture/index.rst @@ -62,7 +62,7 @@ Connectivity management Connectivity Management is the layer that connects your SmartThings Hub, the client devices (mobile phones) to SmartThings servers and to the cloud as a whole. The Connectivity Management layer is comprised of: -- Hub Connectivity that connects your hub to the cloud. +- Hub Connectivity that connects your Hub to the cloud. - Client Connectivity that connects your client devices to the cloud. These are the highways by which your messages are sent to the internet. @@ -72,15 +72,15 @@ Device Handler execution The SmartThings system determines what type of device you are using based on Device Handlers. Once the Device Handler is selected, the incoming messages are parsed by that particular Device Handler. -The input to the Device Handler is a set of device-specific messages, and the output of the Device Handler is normalized SmartThings events. -Note that one message can lead to many SmartThings events. +The input to the Device Handler is a set of device-specific messages, and the output of the Device Handler is normalized SmartThings Events. +Note that one message can lead to many SmartThings Events. Subscription management ^^^^^^^^^^^^^^^^^^^^^^^ -When events are created in the SmartThings platform, they don't inherently do anything besides publish that they've happened. -Instead of events triggering change, SmartApps are configured with subscriptions that listen for defined events. -The purpose of the subscription management layer is to match up events that are triggered by the Device Handlers with the SmartApp that is using them. +When Events are created in the SmartThings platform, they don't inherently do anything besides publish that they've happened. +Instead of Events triggering change, SmartApps are configured with subscriptions that listen for defined Events. +The purpose of the subscription management layer is to match up Events that are triggered by the Device Handlers with the SmartApp that is using them. SmartApp execution ^^^^^^^^^^^^^^^^^^ @@ -92,11 +92,11 @@ Any data that needs to persist throughout SmartApp instances must be stored in a Web UI and IDE ^^^^^^^^^^^^^^ -The Web UI sits on top of all of the other technology and allows you to monitor your devices, hubs, locations and many other aspects of your SmartThings system. +The Web UI sits on top of all of the other technology and allows you to monitor your devices, Hubs, Locations and many other aspects of your SmartThings system. You have full control of the configuration, including editing, adding, removing, and even creating SmartApps. To create, you write code within the IDE for SmartApps and Device Handlers. -SmartThings also has an integrated simulator that allows you to simulate any devices, so it's not required to own the devices you develop for. +SmartThings also has an integrated Simulator that allows you to simulate any devices, so it's not required to own the devices you develop for. Important concepts ------------------ @@ -117,7 +117,7 @@ This means that you execute a command, and assume it will turn on in due time, w You cannot be guaranteed that your command has been executed, because another SmartApp could interact with your end device, and change its state. For example, you might turn a light switch on, but another app might sneak in and turn it off. -If you need to know if a command was executed, you can subscribe to an event triggered by the command you executed and check its timestamp to ensure it fired after you told it to. +If you need to know if a command was executed, you can subscribe to an Event triggered by the command you executed and check its timestamp to ensure it fired after you told it to. You will, however, still have latency issues to take into consideration, so it's impossible to know the exact current status at any given time. The SmartApps platform follows eventually consistent programming, meaning that responses to a request for a value in SmartApps will eventually be the same, but in the short term they might differ. @@ -126,7 +126,7 @@ Containers ^^^^^^^^^^ Within the SmartThings platform, there are three different “containers” that are important concepts to understand. -These are: *accounts, locations,* and *groups.* +These are: *accounts, Locations,* and *groups.* These containers represent both security boundaries and navigation containers that make it easy for users to browse their devices. The diagram below shows the hierarchical relationship between these containers. @@ -153,7 +153,7 @@ Finally, locations contain Groups or Devices. Groups ^^^^^^ -Groups are meant to represent a room or other physical space within a location. +Groups are meant to represent a room or other physical space within a Location. This allows for devices to be organized into groups making navigation and security easier. A group can contain multiple devices, but devices can only be in a single group. Further, nesting of groups is not currently supported. @@ -199,7 +199,7 @@ SmartThings cloud The SmartThings platform assumes a "Cloud First” approach. This means that in order to use all supported devices and automations, and to ensure that the SmartThings mobile application reflects the correct state of your home, the SmartThings Hub will need to be online and be connected to the SmartThings cloud. -The second generation of the hub, the Samsung SmartThings Hub, allows for some hub-local capabilities. +The second generation Hub, the Samsung SmartThings Hub, allows for some Hub-local capabilities. Certain automations can execute even when disconnected from the SmartThings cloud. This allows SmartThings to improve performance and insulate the user from intermittent internet outages. @@ -223,13 +223,13 @@ Put simply, if there is no Hub, then the SmartApps layer must run in the cloud! **Scenario: SmartApps may run across both cloud- and Hub-connected devices** -As a corollary to the first point above, since there are use cases where devices are not hub-connected, SmartApps might be installed to use one device that is hub-connected, and another device that is cloud-connected, all in the same app. +As a corollary to the first point above, since there are use cases where devices are not Hub-connected, SmartApps might be installed to use one device that is Hub-connected, and another device that is Cloud-connected, all in the same app. In this case, the SmartApp needs to run in the cloud. **Scenario: There may be multiple Hubs** While the mesh network standards for ZigBee and Z-Wave generally eliminate the need for multiple SmartThings Hubs, we didn’t want to exclude this as a valid deployment configuration for large homes or even business applications of our technology. -In the multi-hub case, SmartApps that use multiple devices that are split across hubs will run in the cloud in order to simplify the complexity of application deployment. +In the multi-Hub case, SmartApps that use multiple devices that are split across hubs will run in the cloud in order to simplify the complexity of application deployment. **Scenario: External service integration** @@ -255,27 +255,27 @@ Hubs and Locations ------------------ To efficiently manage performance, the SmartThings platform scales its cloud server architecture horizontally with *sharding*. -Sharding helps reduce the latency between the hub and the cloud, and handles increasing capacity. +Sharding helps reduce the latency between the Hub and the cloud, and handles increasing capacity. As a developer you must note the impact of sharding on how you work with the SmartThings IDE. -When you first install SmartThings app on your mobile phone, create your user account and claim your hub, the SmartThings platform automatically assigns your hub to the location and connects your location/hub to a particular shard. +When you first install SmartThings app on your mobile phone, create your user account and claim your Hub, the SmartThings platform automatically assigns your Hub to the Location and connects your Location/Hub to a particular shard. Before starting your development, you must note that: -- Your location/hub is connected to a *specific* SmartThings shard, based on the geographical location of the hub, and, -- You must ensure that you are logged into the URL of this specific shard on IDE. Since the location is always connected to the correct shard URL, you can do this by clicking on your location from "My Locations" page after you log in. +- Your Location/Hub is connected to a *specific* SmartThings shard, based on the geographical location of the Hub, and, +- You must ensure that you are logged into the URL of this specific shard on IDE. Since the Location is always connected to the correct shard URL, you can do this by clicking on your Location from "My Locations" page after you log in. .. note:: - If for some reason you are not seeing your hub in the IDE, then from *My Locations* page select the location and it will prompt you to log into correct shard where you can see your hub. + If for some reason you are not seeing your Hub in the IDE, then from *My Locations* page select the Location and it will prompt you to log into correct shard where you can see your Hub. Consequences of sharding ^^^^^^^^^^^^^^^^^^^^^^^^ In practice, some consequences of sharding are: -- A global layer, with a few specific services, spans across all shards while all other services are owned by the specific shard itself (which, as emphasized above, is location-dependent). A few global layer services are: user account creation, authorization, OAuth authentication, mappings of location-to-shard, users-to-locations and hub-to-locations. All data that is down from the location level are managed by the specific shard. +- A global layer, with a few specific services, spans across all shards while all other services are owned by the specific shard itself (which, as emphasized above, is Location-dependent). A few global layer services are: user account creation, authorization, OAuth authentication, mappings of Location-to-shard, users-to-Locations and Hub-to-Locations. All data that is down from the Location level are managed by the specific shard. - A shard does not share information with another shard. For example, a common login across the shards does not exist yet. You will have to log in to each shard, although the userid and password will be the same (see the note above). At the same time, note that SmartThings mobile app users do not have to log in again because mobile client OAuth tokens are shared across the shards. -- SmartApps and Device Handlers are now published in a specific shard and not for your entire account. For example, if you have a hub in North America and another hub in Europe, you will need to publish your SmartApp twice, one in each location, i.e., shard. -- Note that since a hub is assigned to a location, if you delete a location, the hub becomes unclaimed. Conversely, it is possible for a location to exist without a claimed hub at that location. +- SmartApps and Device Handlers are now published in a specific shard and not for your entire account. For example, if you have a Hub in North America and another Hub in Europe, you will need to publish your SmartApp twice, one in each Location, i.e., shard. +- Note that since a Hub is assigned to a Location, if you delete a Location, the Hub becomes unclaimed. Conversely, it is possible for a Location to exist without a claimed Hub at that Location. .. |Container Hierarchy| image:: ../img/architecture/overview.png diff --git a/arduino/index.rst b/arduino/index.rst index fed14c93..fc1d3c0a 100644 --- a/arduino/index.rst +++ b/arduino/index.rst @@ -31,7 +31,7 @@ You can download the `SmartThings Arduino Library here `__. Pairing the shield ------------------ -To join the shield to your SmartThings hub, go to “Add SmartThings” mode in the +To join the shield to your SmartThings Hub, go to “Add SmartThings” mode in the SmartThings app by hitting the “+” icon in the desired location, and then press the Switch button on the shield. You should see the shield appear in the app. To unpair the shield, press and hold the Switch button for 6 seconds and release. The shield will now be unpaired from your SmartThings Hub. Make sure to delete from your account if you plan to re-pair it! @@ -39,7 +39,7 @@ To unpair the shield, press and hold the Switch button for 6 seconds and release Changing the Device Handler --------------------------- -By changing the Device Handler in the SmartThings cloud you can change how to interact with your Arduino + ThingShield. When a shield first pairs, it has no functionality and only serves to help identify the device in the mobile app. We have some pre-built Device Handlers that you can use for most functionality. One pre-built Arduino device handler is the “On/Off Shield (example)” +By changing the Device Handler in the SmartThings cloud you can change how to interact with your Arduino + ThingShield. When a shield first pairs, it has no functionality and only serves to help identify the device in the mobile app. We have some pre-built Device Handlers that you can use for most functionality. One pre-built Arduino Device Handler is the “On/Off Shield (example)” To change your Device Handler, log into `http://graph.api.smartthings.com/` and click on “Devices” Navigate to and click on the Arduino ThingShield then click on “Edit” on the bottom left of the page. @@ -51,7 +51,7 @@ Hit the "Update" button Your Arduino will now be able to accept the commands "on" "off", and "hello" -`Here is what the Arduino sketch looks like `__ and here is the `device handler `__. +`Here is what the Arduino sketch looks like `__ and here is the `Device Handler `__. `Here is a different Device Handler that can read a string sent from an Arduino and display it in a tile `__. diff --git a/cloud-and-lan-connected-device-types-developers-guide/building-cloud-connected-device-types/building-the-device-type.rst b/cloud-and-lan-connected-device-types-developers-guide/building-cloud-connected-device-types/building-the-device-type.rst index c42b3ea3..15fbb637 100644 --- a/cloud-and-lan-connected-device-types-developers-guide/building-cloud-connected-device-types/building-the-device-type.rst +++ b/cloud-and-lan-connected-device-types-developers-guide/building-cloud-connected-device-types/building-the-device-type.rst @@ -1,26 +1,26 @@ Building the Device Handler =========================== -The Device Handler for a cloud-connected device is generally the same as any other device handler. +The Device Handler for a Cloud-connected device is generally the same as any other Device Handler. The means in which -it handles sending and receiving messages from its device is a little bit different. -Let's walk through a cloud connected -device handler example. +it handles sending and receiving messages from its device is a little bit different. +Let's walk through a Cloud-connected +Device Handler example. The Parse method ---------------- -The parse method for cloud connected devices will always be empty. In a -cloud connected device, event data is passed down from the service -manager, not from the device itself, so the parsing is handled in a +The parse method for Cloud-connected devices will always be empty. In a +Cloud-connected device, Event data is passed down from the Service +Manager, not from the device itself, so the parsing is handled in a separate method. The Device Handler doesn't interface directly with a hardware device, which is what parse is used for. Sending commands to the third-party cloud ----------------------------------------- -Usually the actual implementation of device methods are delegated to its service manager. This is because the service -manager is the entity that has the authentication information. To invoke a method on the parent service manager, +Usually the actual implementation of device methods are delegated to its Service Manager. This is because the Service +Manager is the entity that has the authentication information. To invoke a method on the parent Service Manager, you simply need to call it in the following format: .. code-block:: groovy @@ -30,7 +30,7 @@ you simply need to call it in the following format: As with any other device-type, you need to define methods for all of the possible commands for the capabilities you'd like to support. Then when a user calls this method, it will pass information up to the parent -service manager, who will make the direct connection to the third party +Service Manager, who will make the direct connection to the third party cloud. You might for example want to turn a switch on, so you would call the following. @@ -44,8 +44,8 @@ Receiving Events from the third-party cloud ------------------------------------------- The Device Handler continuously polls the third-party cloud through -the service manager to check on the status of devices. When an event is -fired, they can then be passed to the child device handler. Note that +the service manager to check on the status of devices. When an Event is +fired, they can then be passed to the child Device Handler. Note that poll runs every 10 minutes for Service Manager SmartApps. In the device-type handler: @@ -92,7 +92,7 @@ Generating Events at the request of the Service Manager ------------------------------------------------------- You won't generate events directly within the Service Manager, but -rather request that they are generated within the Device-type handler. +rather request that they are generated within the Device Handler. For example: In the service manager: @@ -101,7 +101,7 @@ In the service manager: childName.generateEvent(data) -In the device handler: +In the Device Handler: .. code-block:: groovy @@ -110,4 +110,4 @@ In the device handler: sendEvent(name: name, value: value) } return null - } \ No newline at end of file + } diff --git a/cloud-and-lan-connected-device-types-developers-guide/building-cloud-connected-device-types/division-of-labor.rst b/cloud-and-lan-connected-device-types-developers-guide/building-cloud-connected-device-types/division-of-labor.rst index 4eee874f..b543c0a1 100644 --- a/cloud-and-lan-connected-device-types-developers-guide/building-cloud-connected-device-types/division-of-labor.rst +++ b/cloud-and-lan-connected-device-types-developers-guide/building-cloud-connected-device-types/division-of-labor.rst @@ -1,9 +1,9 @@ Division of Labor ================= -The Cloud-connected device paradigm consists of a Service Manager and Device Handlers. +The Cloud-connected device paradigm consists of a Service Manager and Device Handlers. The purpose of this guide is -to introduce you to the core concepts of cloud connected device development, and provide some examples to help you get +to introduce you to the core concepts of Cloud-connected device development, and provide some examples to help you get started. @@ -19,7 +19,7 @@ your connection to be able to make future interactions with the device. Device Handler responsibilities ------------------------------- -The device handler is responsible for creating and receiving device +The Device Handler is responsible for creating and receiving device specific messages, and allowing them to work within the SmartThings infrastructure. It takes in a SmartApp specific command and outputs device specific commands to be passed to the cloud. It also allows you @@ -29,7 +29,7 @@ needed. How it all works ---------------- -The following depiction gives a general overview of how a cloud connected device works. Take note of +The following depiction gives a general overview of how a Cloud-connected device works. Take note of the Service Manager and Device Handler. We will dive into how to build these next. .. image:: ../../img/architecture/cloud_overview.png diff --git a/cloud-and-lan-connected-device-types-developers-guide/building-cloud-connected-device-types/index.rst b/cloud-and-lan-connected-device-types-developers-guide/building-cloud-connected-device-types/index.rst index 346e3674..2632c323 100644 --- a/cloud-and-lan-connected-device-types-developers-guide/building-cloud-connected-device-types/index.rst +++ b/cloud-and-lan-connected-device-types-developers-guide/building-cloud-connected-device-types/index.rst @@ -1,14 +1,14 @@ Building Cloud-connected Device Types ===================================== -Cloud-connected devices use a third-party service to accomplish device communication. +Cloud-connected devices use a third-party service to accomplish device communication. An example of such a device is the Ecobee thermostat. -When developing a device handler for a cloud connected device, you must create a service manager SmartApp that will handle authenticating with the 3rd party service, communicating with the device, and reacting to any device changes that occur. +When developing a Device Handler for a Cloud-connected device, you must create a Service Manager SmartApp that will handle authenticating with the third-party service, communicating with the device, and reacting to any device changes that occur. -This guide overviews the concept of the service manager/device handler architecture and -also gives an example of both the service manager and device handler creation. +This guide overviews the concept of the Service Manager/Device Handler architecture and +also gives an example of both the Service Manager and Device Handler creation. Table of Contents: diff --git a/cloud-and-lan-connected-device-types-developers-guide/building-lan-connected-device-types/building-the-device-type.rst b/cloud-and-lan-connected-device-types-developers-guide/building-lan-connected-device-types/building-the-device-type.rst index f3da1dcd..86578bb0 100644 --- a/cloud-and-lan-connected-device-types-developers-guide/building-lan-connected-device-types/building-the-device-type.rst +++ b/cloud-and-lan-connected-device-types-developers-guide/building-lan-connected-device-types/building-the-device-type.rst @@ -3,15 +3,15 @@ Building the Device Type ======================== -The device handler for a LAN connected device is generally the same as any other device handler. The means in which -it handles sending and receiving messages from its device is a little bit different. Let's walk through a LAN connected -device handler example. +The Device Handler for a LAN-connected device is generally the same as any other Device Handler. The means in which +it handles sending and receiving messages from its device is a little bit different. Let's walk through a LAN-connected +Device Handler example. Making outbound HTTP calls with HubAction ----------------------------------------- Depending on the type of device you are using, you will send requests to -your devices through the hub via REST or UPnP. You can do this using +your devices through the Hub via REST or UPnP. You can do this using the SmartThings provided ``HubAction`` class. ---- @@ -27,7 +27,7 @@ request, such as the request method, headers, and path. By itself, ``HubAction`` It is when an instance of a ``HubAction`` is returned from a command method that it becomes useful. -When a command method of your device handler returns an instance of a ``HubAction``, the SmartThings platform will use the request information within it to actually perform the request. It will then call the device-handler's ``parse`` method with any response data. +When a command method of your Device Handler returns an instance of a ``HubAction``, the SmartThings platform will use the request information within it to actually perform the request. It will then call the device-handler's ``parse`` method with any response data. Herein lies an important point - *if your HubAction instance is not returned from your command method, no request will be made.* It will just be an object allocating system memory. Not very useful. @@ -97,13 +97,13 @@ For more information about the JSON or XML response formats, see the Groovy `Jso Getting the addresses --------------------- -To use HubAction, you will need the IP address of the device, and sometimes the hub. +To use HubAction, you will need the IP address of the device, and sometimes the Hub. How the device IP and port are stored my vary depending on the device type. There's currently not a public API to get this information easily, so until there is, you will need to handle this in your device-type handler. Consider using helper methods like these to get this information: .. code-block:: groovy - // gets the address of the hub + // gets the address of the Hub private getCallBackAddress() { return device.hub.getDataValue("localIP") + ":" + device.hub.getDataValue("localSrvPortTCP") } @@ -229,8 +229,8 @@ Here's an example of using ``HubSoapAction``: Subscribing to device Events ---------------------------- -If you'd like to hear back from a LAN connected device upon a particular -event, you can subscribe using a ``HubAction``. The ``parse`` method will be called when this event is fired on the device. +If you'd like to hear back from a LAN-connected device upon a particular +Event, you can subscribe using a ``HubAction``. The ``parse`` method will be called when this Event is fired on the device. Here's an example using UPnP: diff --git a/cloud-and-lan-connected-device-types-developers-guide/building-lan-connected-device-types/building-the-service-manager.rst b/cloud-and-lan-connected-device-types-developers-guide/building-lan-connected-device-types/building-the-service-manager.rst index a4ab76b4..15b7da4a 100644 --- a/cloud-and-lan-connected-device-types-developers-guide/building-lan-connected-device-types/building-the-service-manager.rst +++ b/cloud-and-lan-connected-device-types-developers-guide/building-lan-connected-device-types/building-the-service-manager.rst @@ -30,17 +30,17 @@ Simple Service Discovery Protocol (SSDP) is the main protocol used to find devic allows you to easily connect new network devices to a system. See `UPnP Device Architecture 1.1 `__ for full specification details. -To discover new devices, you first need to subscribe to location events with the correct **search target** for the device. The +To discover new devices, you first need to subscribe to Location Events with the correct **search target** for the device. The search target in the below example, **urn:schemas-upnp-org:device:ZonePlayer:1**, is for discovery of a Sonos, but search targets will vary by manufacturer and device. For UPnP, this information should be published on documentation for the device, but you may -alternatively have to contact the manufacturer directly to obtain it. Here is the event subscription: +alternatively have to contact the manufacturer directly to obtain it. Here is the Event subscription: .. code-block:: groovy subscribe(location, "ssdpTerm.urn:schemas-upnp-org:device:ZonePlayer:1", ssdpHandler) This means that any time an SSDP **search response** with a search target of urn:schemas-upnp-org:device:ZonePlayer:1 -(e.g. Sonos) is received from a hub in this location, it will fire the ssdpHandler method. +(e.g. Sonos) is received from a Hub in this Location, it will fire the ssdpHandler method. Next, you need to send an appropriate discovery command for the desired search target: @@ -59,13 +59,13 @@ Next, you need to send an appropriate discovery command for the desired search t request, such as the request method, headers, and path. By itself, ``HubAction`` is little more than a wrapper for these request details. In this case, it's a thin wrapper around discovery information. -In the above HubAction example, the main message to be sent through the hub is: +In the above HubAction example, the main message to be sent through the Hub is: .. code-block:: groovy lan discovery urn:schemas-upnp-org:device:ZonePlayer:1 -This is converted by our device connectivity layer into an M-SEARCH multicast request that is sent to the LAN via the hub, and +This is converted by our device connectivity layer into an M-SEARCH multicast request that is sent to the LAN via the Hub, and should look something like the following: .. code-block:: bash @@ -77,7 +77,7 @@ should look something like the following: ST: urn:schemas-upnp-org:device:ZonePlayer:1 After the end device receives the multicast M-SEARCH, it is supposed to issue a unicast **search response**, delayed by a random number of seconds between 0 and MX (4 in this case). -The search response sent from the device back to the hub should look something like this: +The search response sent from the device back to the Hub should look something like this: .. code-block:: bash @@ -89,7 +89,7 @@ The search response sent from the device back to the hub should look something l ST: urn:schemas-upnp-org:device:ZonePlayer:1 USN: uuid:RINCON_000E58F0FFFFFF400::urn:schemas-upnp-org:device:ZonePlayer:1 -This will get routed back to the cloud where it will be converted into an event that will fire the ssdpHandler method with the following description: +This will get routed back to the cloud where it will be converted into an Event that will fire the ssdpHandler method with the following description: .. code-block:: bash @@ -120,10 +120,10 @@ Verification Once we've recorded the presence of a device on the LAN with the desired SSDP search target, the next step is to verify the availability of the device by fetching some more information about it. In UPnP, this is called the **device description**. -In the search response, there is a LOCATION header which shows the location of the device description on the LAN. SmartThings -splits this into **networkAddress**, **deviceAddress**, and **ssdpPath** in the event, which at this point should exist in app state. +In the search response, there is a LOCATION header which shows the Location of the device description on the LAN. SmartThings +splits this into **networkAddress**, **deviceAddress**, and **ssdpPath** in the Event, which at this point should exist in app state. This can be pulled out of state and put into a HubAction. Note that the HubAction has a **callback**, which means that -when an HTTP response is issued from the device to the hub, it will fire the **deviceDescriptionHandler** method. +when an HTTP response is issued from the device to the Hub, it will fire the **deviceDescriptionHandler** method. .. code-block:: groovy @@ -148,14 +148,14 @@ when an HTTP response is issued from the device to the hub, it will fire the **d .. note:: HubResponse is a class supplied by the SmartThings platform. Here are some pieces of data that are included: - * **description** - The raw message received by the device connectivity layer. - * **hubId** - The UUID of the SmartThings hub that received the response. - * **status** - HTTP status code of the response. - * **headers** - Map of the HTTP headers of the response. - * **body** - String of the HTTP response body. - * **error** - Any error encountered during any automatic parsing of the body as either JSON or XML. - * **json** - If the HTTP response has a Content-Type header of application/json, the body is automatically parsed as JSON and stored here. - * **xml** - If the HTTP response has a Content-Type header of text/xml, the body is automatically parsed as XML and stored here. + * **description** - The raw message received by the device connectivity layer + * **hubId** - The UUID of the SmartThings Hub that received the response + * **status** - HTTP status code of the response + * **headers** - Map of the HTTP headers of the response + * **body** - String of the HTTP response body + * **error** - Any error encountered during any automatic parsing of the body as either JSON or XML + * **json** - If the HTTP response has a Content-Type header of application/json, the body is automatically parsed as JSON and stored here + * **xml** - If the HTTP response has a Content-Type header of text/xml, the body is automatically parsed as XML and stored here ---- diff --git a/cloud-and-lan-connected-device-types-developers-guide/building-lan-connected-device-types/division-of-labor.rst b/cloud-and-lan-connected-device-types-developers-guide/building-lan-connected-device-types/division-of-labor.rst index d1ff26b5..d3bf0227 100644 --- a/cloud-and-lan-connected-device-types-developers-guide/building-lan-connected-device-types/division-of-labor.rst +++ b/cloud-and-lan-connected-device-types-developers-guide/building-lan-connected-device-types/division-of-labor.rst @@ -2,7 +2,7 @@ Division of Labor ================= The LAN-connected device paradigm consists of a Service Manager and Device Handlers. The purpose of this guide is -to introduce you to the core concepts of LAN connected device development, and provide some examples to help you get +to introduce you to the core concepts of LAN-connected device development, and provide some examples to help you get started. Service Manager responsibilities @@ -17,7 +17,7 @@ able to make future interactions with the device. Device Handler responsibilities ------------------------------- -The device handler is responsible for creating and receiving device +The Device Handler is responsible for creating and receiving device specific messages, and allowing them to work within the SmartThings infrastructure. It takes in a SmartApp-specific command and outputs device specific commands. It also allows you to subscribe to responses diff --git a/cloud-and-lan-connected-device-types-developers-guide/building-lan-connected-device-types/index.rst b/cloud-and-lan-connected-device-types-developers-guide/building-lan-connected-device-types/index.rst index f425d5c9..e5d089a8 100644 --- a/cloud-and-lan-connected-device-types-developers-guide/building-lan-connected-device-types/index.rst +++ b/cloud-and-lan-connected-device-types-developers-guide/building-lan-connected-device-types/index.rst @@ -1,15 +1,15 @@ Building LAN-connected Device Types =================================== -LAN-connected devices communicate with the SmartThings hub over the LAN. +LAN-connected devices communicate with the SmartThings Hub over the LAN. An example of such a device is the Sonos system. -When developing a device handler for a LAN device, you must create a service manager +When developing a Device Handler for a LAN device, you must create a service manager SmartApp that will handle discovery of devices on the LAN, in some cases communicate with the device, and react to any -device changes that occur via events. +device changes that occur via Events. -This guide overviews the concept of the service manager/device handler architecture -and also gives an example of both the service manager and device handler creation. +This guide overviews the concept of the Service Manager/Device Handler architecture +and also gives an example of both the Service Manager and Device Handler creation. Table of Contents: diff --git a/cloud-and-lan-connected-device-types-developers-guide/index.rst b/cloud-and-lan-connected-device-types-developers-guide/index.rst index cb263cc9..2e94b2c9 100644 --- a/cloud-and-lan-connected-device-types-developers-guide/index.rst +++ b/cloud-and-lan-connected-device-types-developers-guide/index.rst @@ -3,9 +3,9 @@ Cloud- and LAN-connected Devices ================================ -Cloud- and LAN-connected devices are devices that use either a third-party service, like the Ecobee thermostat, or communicate over the LAN (local area network) like the Sonos system. -These devices require a unique implementation of their Device Handlers. -Cloud- and LAN-connected devices use a Service Manager SmartApp along with a device handler for authentication, maintaining connections, and device communications. +Cloud- and LAN-connected devices are devices that use either a third-party service, like the Ecobee thermostat, or communicate over the LAN (local area network) like the Sonos system. +These devices require a unique implementation of their Device Handlers. +Cloud- and LAN-connected devices use a Service Manager SmartApp along with a Device Handler for authentication, maintaining connections, and device communications. This guide will walk you through Service Manager and Device Handler creation for both of these scenarios. Table of Contents: diff --git a/cloud-and-lan-connected-device-types-developers-guide/understanding-the-service-manage-device-handler-design-pattern.rst b/cloud-and-lan-connected-device-types-developers-guide/understanding-the-service-manage-device-handler-design-pattern.rst index 0aa8352b..310dc578 100644 --- a/cloud-and-lan-connected-device-types-developers-guide/understanding-the-service-manage-device-handler-design-pattern.rst +++ b/cloud-and-lan-connected-device-types-developers-guide/understanding-the-service-manage-device-handler-design-pattern.rst @@ -6,22 +6,22 @@ Basic overview Devices that connect through the internet as a whole (cloud) or LAN devices (on your local network) require a defined Service-Manager -SmartApp, in addition to the usually expected Device Handler. -The Service Manager makes the connection with the device, handling the input and output interactions, and the device handler parses messages. +SmartApp, in addition to the usually expected Device Handler. +The Service Manager makes the connection with the device, handling the input and output interactions, and the Device Handler parses messages. Cloud-connected devices ----------------------- -When using a cloud-connected device, the service manager is used to -discover and initiate a connection between the device and your hub, -using OAuth connections to external third parties. -Then the device-handler uses this connection to communicate between the hub and device. +When using a Cloud-connected device, the service manager is used to +discover and initiate a connection between the device and your Hub, +using OAuth connections to external third parties. +Then the Device Handler uses this connection to communicate between the Hub and device. LAN-connected devices --------------------- When using a LAN-connected device, the service manager is used to -discover and initiate a connection between the device and your hub, -using the protocols SSDP or mDNS/DNS-SD. +discover and initiate a connection between the device and your Hub, +using the protocols SSDP or mDNS/DNS-SD. Then the device-handler uses UPnP/SOAP Calls or REST Calls to communicate outgoing messages between -the hub and device. \ No newline at end of file +the Hub and device. diff --git a/code-review-guidelines.rst b/code-review-guidelines.rst index c3b11b69..80e3dd74 100644 --- a/code-review-guidelines.rst +++ b/code-review-guidelines.rst @@ -291,7 +291,7 @@ Using State Do not think of state as a virtually unlimited database for your app. The amount of data that can be stored in state is :ref:`limited `. -Avoid code that adds items to ``state`` regularly (perhaps in response to events or schedules), but does not remove items. +Avoid code that adds items to ``state`` regularly (perhaps in response to Events or schedules), but does not remove items. Understand how ``state`` works ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -353,7 +353,7 @@ Security considerations Subscriptions should be clear ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -It is possible to subscribe to events using a string variable, so what the SmartApp is subscribing to might be somewhat opaque. +It is possible to subscribe to Events using a string variable, so what the SmartApp is subscribing to might be somewhat opaque. For example: @@ -378,8 +378,8 @@ Subscriptions should be specific Do not create overly-broad subscriptions. -A SmartApp that is subscribed to every location event will execute excessively, and is rarely necessary. -Instead, create subscriptions specific to the event you are interested in. +A SmartApp that is subscribed to every location Event will execute excessively, and is rarely necessary. +Instead, create subscriptions specific to the Event you are interested in. If you're creating a service manager for a LAN-connected device, be sure to :ref:`subscribe to the device search target `. @@ -450,7 +450,7 @@ Do not use ``synchronized()`` Using ``synchronized`` incurs a performance overhead, and is highly unlikely to have any effect. It should not be used. -When a SmartApp or Device Handler executes, it is executing on one of *n* available servers assigned for that location, where *n* is variable depending on location, current load, and other factors. +When a SmartApp or Device Handler executes, it is executing on one of *n* available servers assigned for that Location, where *n* is variable depending on Location, current load, and other factors. Concurrent executions of the SmartApp or Device Handler are not guaranteed, or even likely, to be executing on the same server. Because of this, trying to force synchronous behavior by using ``synchronized`` would only work in the rare occurrence that a concurrent execution happens on the same server, yet it always incurs overhead. diff --git a/device-type-developers-guide/building-z-wave-device-handlers.rst b/device-type-developers-guide/building-z-wave-device-handlers.rst index 384e6910..d1b9dddf 100644 --- a/device-type-developers-guide/building-z-wave-device-handlers.rst +++ b/device-type-developers-guide/building-z-wave-device-handlers.rst @@ -11,7 +11,7 @@ SmartThings provides custom Z-Wave command objects that represent the standard c Parsing Events -------------- -When events from Z-Wave devices are passed into your Device hHandler's parse method, they are in an encoded string format. +When Events from Z-Wave devices are passed into your Device hHandler's parse method, they are in an encoded string format. The first thing your parse method should do is call ``zwave.parse`` on the description string to convert it to a Z-Wave command object. The object's class is one of the subclasses of ``physicalgraph.zwave.Command`` that can be found in the `Z-Wave Command Reference `__. @@ -67,7 +67,7 @@ commands you intend to handle: return createEvent(descriptionText: "${device.displayName}: ${cmd}") } -Remember that when you use ``createEvent()`` to build an event, the resulting map must be returned from ``parse()`` for the event to be sent. +Remember that when you use ``createEvent()`` to build an Event, the resulting map must be returned from ``parse()`` for the Event to be sent. For information about ``createEvent``, see the `Creating Events `__ section. As the `Z-Wave Command Reference `__ shows, many Z-Wave command classes have multiple versions. @@ -119,15 +119,15 @@ This example returns the output of ``delayBetween``, and thus will send a BasicS ---- -Sending commands in response to events +Sending commands in response to Events -------------------------------------- In some situations, instead of sending a command in response to a request by the user, you want to automatically send a command to the device on receipt of a Z-Wave command. If you return a list from the parse method, each item of the list will be evaluated separately. -Items that are maps will be processed as events as usual and sent to subscribed SmartApps and mobile clients. -Returned items that are HubAction items, however, will be sent via the hub to the device, in much the same way as formatted commands returned from command methods. -The easiest way to send a command to a device in response to an event is the ``response()`` helper, which takes a Z-Wave command or encoded string and supplies a HubAction: +Items that are maps will be processed as Events as usual and sent to subscribed SmartApps and mobile clients. +Returned items that are HubAction items, however, will be sent via the Hub to the device, in much the same way as formatted commands returned from command methods. +The easiest way to send a command to a device in response to an Event is the ``response()`` helper, which takes a Z-Wave command or encoded string and supplies a HubAction: .. code-block:: groovy @@ -141,6 +141,6 @@ The easiest way to send a command to a device in response to an event is the ``r [event, response(cmds)] // return a list containing the event and the result of response() } -The above example uses the ``response()`` helper to send Z-Wave commands and delay commands to the device whenever a WakeUpNotification event is received. -The reception of this event that indicates that the sleepy device is temporarily listening for commands. -In addition to creating a hidden event, the handler will send a BatteryGet request, wait 1.2 seconds for a response, and then issue a WakeUpNoMoreInformation command to tell the device it can go back to sleep to save battery. +The above example uses the ``response()`` helper to send Z-Wave commands and delay commands to the device whenever a WakeUpNotification Event is received. +The reception of this Event that indicates that the sleepy device is temporarily listening for commands. +In addition to creating a hidden Event, the handler will send a BatteryGet request, wait 1.2 seconds for a response, and then issue a WakeUpNoMoreInformation command to tell the device it can go back to sleep to save battery. diff --git a/device-type-developers-guide/building-zigbee-device-handlers.rst b/device-type-developers-guide/building-zigbee-device-handlers.rst index 450a722f..62dfe35c 100644 --- a/device-type-developers-guide/building-zigbee-device-handlers.rst +++ b/device-type-developers-guide/building-zigbee-device-handlers.rst @@ -114,9 +114,9 @@ Configure reporting instructs a device to notify us when an attribute changes an } In this example (using the "CentraLite Switch" Device Handler), the bind command is sent to the device using its Network ID which can be determined using ``0x${device.deviceNetworkId}``. -Then using source and destination endpoints for the device and hub (1 1), we bind to the On/Off Clusters (6) to get events from the device. -The last part of the message contains the hub's ZigBee id which is set as the location for the device to send callback messages to. -Note that not at all devices support binding for events. +Then using source and destination endpoints for the device and Hub (1 1), we bind to the On/Off Clusters (6) to get Events from the device. +The last part of the message contains the Hub's ZigBee id which is set as the Location for the device to send callback messages to. +Note that not at all devices support binding for Events. +-------------------------------+-----------------------------+ | Component | Description | @@ -150,7 +150,7 @@ Best practices -------------- - The use of 'raw ...' commands is deprecated. Instead use the documented methods on the ZigBee library. If you need to do something that requires the use of a 'raw' command let us know and we will look at adding it to the ZigBee library. -- Do not use ``sendEvent()`` in command methods. Sending events should be handled in the ``parse`` method. +- Do not use ``sendEvent()`` in command methods. Sending Events should be handled in the ``parse`` method. ---- diff --git a/device-type-developers-guide/definition-metadata.rst b/device-type-developers-guide/definition-metadata.rst index 1b688bde..0a4d9eda 100644 --- a/device-type-developers-guide/definition-metadata.rst +++ b/device-type-developers-guide/definition-metadata.rst @@ -121,7 +121,7 @@ To define a custom command for your Device Handler, call the ``command()`` metho Fingerprinting -------------- -When a ZigBee or Z-Wave device is added to the SmartThings hub, we need a way to determine which device type to assign it. +When a ZigBee or Z-Wave device is added to the SmartThings Hub, we need a way to determine which device type to assign it. This process is known as a "join" process, or "fingerprinting". Device Handlers define "fingerprints" to specify which devices or what kinds of devices they support. diff --git a/device-type-developers-guide/device-integration.rst b/device-type-developers-guide/device-integration.rst index 68dedf9d..0497caa6 100644 --- a/device-type-developers-guide/device-integration.rst +++ b/device-type-developers-guide/device-integration.rst @@ -12,10 +12,10 @@ Examples of devices already certified to work with SmartThings can be viewed `he The device certification process consists of the following steps: -1. **Create** a virtual representation of your device using a :ref:`device_type_dev_guide`. -2. **Test** the device handler by publishing it to your account and pairing your device with your hub. -3. Once you’ve successfully tested your device handler, **submit** it for publication. -4. The SmartThings certification team will contact you about how to **ship** your device to us and complete the certification process. +1. **Create** a virtual representation of your device using a :ref:`device_type_dev_guide` +2. **Test** the Device Handler by publishing it to your account and pairing your device with your Hub +3. Once you’ve successfully tested your Device Handler, **submit** it for publication +4. The SmartThings certification team will contact you about how to **ship** your device to us and complete the certification process | | diff --git a/device-type-developers-guide/device-preferences.rst b/device-type-developers-guide/device-preferences.rst index f3763214..9e058843 100644 --- a/device-type-developers-guide/device-preferences.rst +++ b/device-type-developers-guide/device-preferences.rst @@ -105,7 +105,7 @@ Just as with SmartApp preferences, the name of the preferences input is a refere .. note:: - Preference values are only available to the Device Handler when it is executing in response to events or commands. + Preference values are only available to the Device Handler when it is executing in response to Events or commands. It is not possible to use preference values in other ``metadata`` definitions, including ``tiles()``. ---- @@ -147,7 +147,7 @@ Example log.debug "time: $time" log.debug "options: $options" } - + ---- Additional notes diff --git a/device-type-developers-guide/index.rst b/device-type-developers-guide/index.rst index 121fbca6..c6b48ede 100644 --- a/device-type-developers-guide/index.rst +++ b/device-type-developers-guide/index.rst @@ -9,11 +9,11 @@ If you are new to writing Device Handlers, start with the :doc:`quick-start`. After that, read the :doc:`overview` for a broad discussion about Device Handlers and where they fit in the SmartThings architecture. -The rest of the guide discusses the various components of Device Handlers primarily targeted for hub-connected (ZigBee or Z-Wave) devices (though the common Device Handler principles and patterns apply to other devices as well). +The rest of the guide discusses the various components of Device Handlers primarily targeted for Hub-connected (ZigBee or Z-Wave) devices (though the common Device Handler principles and patterns apply to other devices as well). .. note:: - This guide discusses hub-connected device handlers. For information about LAN and cloud-connected device handlers, see `this guide <../cloud-and-lan-connected-device-types-developers-guide/index.html>`__ + This guide discusses Hub-connected Device Handlers. For information about LAN- and Cloud-connected Device Handlers, see `this guide <../cloud-and-lan-connected-device-types-developers-guide/index.html>`__ Table of Contents: diff --git a/device-type-developers-guide/overview.rst b/device-type-developers-guide/overview.rst index d7e36a8b..d533dd86 100644 --- a/device-type-developers-guide/overview.rst +++ b/device-type-developers-guide/overview.rst @@ -21,7 +21,7 @@ SmartThings architecture. :alt: Smart Things Architecture -In the example shown above, the job of the device handler (that is implementing the "switch" capability) is to parse incoming, protocol-specific status messages from the device and turn them into normalized "events". +In the example shown above, the job of the Device Handler (that is implementing the "switch" capability) is to parse incoming, protocol-specific status messages from the device and turn them into normalized "events". It is also responsible for accepting normalized commands (such as "on" and "off") and turning those into the protocol-specific commands that can be sent to the device to affect the desired action. For example, for a Z-Wave compatible on-off switch, the incoming status messages used by the device to report an "on" or "off" state are as shown below: @@ -35,10 +35,10 @@ off command: 2003, payload: 00 Whereas the device status reported to the SmartThings platform for the device is literally just a simple "on" or "off". -Similarly, when a SmartApp or the mobile app invoked an "on" or "off" command for a switch device, the command that is sent to the device handler is just that simple: "on" or "off". +Similarly, when a SmartApp or the mobile app invoked an "on" or "off" command for a switch device, the command that is sent to the Device Handler is just that simple: "on" or "off". The Device Handler must turn that simple command into a protocol-specific message that can be sent down to the device to affect the desired action. -The table below shows the actual Z-Wave commands that are sent to a Z-Wave switch by the device handler. +The table below shows the actual Z-Wave commands that are sent to a Z-Wave switch by the Device Handler. ============== ================================= Device Command Protocol-Specific Command Message @@ -92,7 +92,7 @@ The above example illustrates how a SmartApp requests a device that supports the The :ref:`capabilities_taxonomy` outlines all the supported capabilities. Device Handlers typically support more than one capability. -A device handler for a Hue bulb would support the "Switch" capability as well as the "Color Control" capability. +A Device Handler for a Hue bulb would support the "Switch" capability as well as the "Color Control" capability. This allows SmartApps to be written in a very flexible manner. Commands and attributes deserve their own discussion - let's dive in. @@ -104,7 +104,7 @@ Commands are the actions that your device can do. For example, a switch can turn on or off, a lock can lock or unlock, and a valve can open or close. In the example above, we issue the "on" and "off" command on the switch by invoking the ``on()`` or ``off()`` methods. -Commands are implemented as methods on the device handler. +Commands are implemented as methods on the Device Handler. When a device supports a capability, it is responsible for implementing all the supported command methods. Attributes @@ -115,8 +115,8 @@ For example, the switch capability defines the attribute "switch", with possible In the example above, we get the value of the "switch" attribute by using the "current" property (``currentSwitch``). -Attribute values are set by creating events where the attribute name is the name of the event, and the attribute value is the value of the event. -This is discussed more in the `Parse and Events documentation `__. +Attribute values are set by creating Events where the attribute name is the name of the Event, and the attribute value is the value of the Event. +This is discussed more in the `Parse and Events documentation `__ Like commands, when a device supports a capability, it is responsible for ensuring that all the capability's attributes are implemented. @@ -130,7 +130,7 @@ These capabilities are "marker" or "tagging" capabilities (if you're familiar wi The "Actuator" capability defines that a device has commands. The "Sensor" capability defines that a device has attributes. -If you are writing a device handler, it is a best practice to support the "Actuator" capability if your device has commands, and the "Sensor" capability if it has attributes. +If you are writing a Device Handler, it is a best practice to support the "Actuator" capability if your device has commands, and the "Sensor" capability if it has attributes. This is why you'll see most Device Handlers supporting one of, or both, of these capabilities. The reason for this is convention and forward-looking abilities - it can allow the SmartThings platform to interact with a variety of devices if they *do* something ("Actuator"), or if they report something ("Sensor"). @@ -142,7 +142,7 @@ Protocols SmartThings currently supports both the `Z-Wave `__ and `ZigBee `__ wireless protocols. -Since the device handler is responsible for communicating between the device and the SmartThings platform, it is usually necessary to understand and communicate in whatever protocol the device supports. +Since the Device Handler is responsible for communicating between the device and the SmartThings platform, it is usually necessary to understand and communicate in whatever protocol the device supports. This guide will discuss both Z-Wave and ZigBee protocols at a high level. ---- @@ -150,8 +150,8 @@ This guide will discuss both Z-Wave and ZigBee protocols at a high level. Execution location ------------------ -With the original SmartThings hub, all Device handlers execute in the SmartThings cloud. -With the new Samsung SmartThings hub, certain Device handlers may run locally on the hub or in the SmartThings cloud. +With the original SmartThings Hub, all Device handlers execute in the SmartThings cloud. +With the new Samsung SmartThings Hub, certain Device handlers may run locally on the Hub or in the SmartThings cloud. Execution location varies depending on a variety of factors, and is managed by the SmartThings internal team. As a SmartThings developer, you should write your Device Handlers to satisfy their specific use cases, regardless of where the handler executes. diff --git a/device-type-developers-guide/parse.rst b/device-type-developers-guide/parse.rst index 1c878336..c76718be 100644 --- a/device-type-developers-guide/parse.rst +++ b/device-type-developers-guide/parse.rst @@ -1,7 +1,7 @@ Parse and Events ================ -The ``parse`` method is the core method in a typical device handler. +The ``parse`` method is the core method in a typical Device Handler. ---- @@ -36,8 +36,8 @@ Consider an example of a simplified ``parse()`` method (modified from the Centra return result } -Our ``parse()`` method inspects the passed-in description, and creates an event with name "switch" and a value of "on" or "off". -It then returns the created event, where the SmartThings platform will handle firing the event and notifying any SmartApps subscribed to that event. +Our ``parse()`` method inspects the passed-in description, and creates an Event with name "switch" and a value of "on" or "off". +It then returns the created Event, where the SmartThings platform will handle firing the Event and notifying any SmartApps subscribed to that Event. ---- @@ -47,7 +47,7 @@ Parse, Events, and Attributes Recall that the "switch" capability specifies an attribute of "switch", with possible values "on" and "off". *The* ``parse()`` *method is responsible for creating events for the attributes of that device's capabilities.* -That is a critical point to understand about Device Handlers - it is what allows SmartApps to respond to event subscriptions! +That is a critical point to understand about Device Handlers - it is what allows SmartApps to respond to Event subscriptions! .. note:: @@ -62,33 +62,33 @@ You should provide the ``name`` and ``value`` at a minimum. .. important:: - The createEvent just creates a data structure (a Map) with information about the event. *It does not actually fire an event.* + The createEvent just creates a data structure (a Map) with information about the Event. *It does not actually fire an Event.* - Only by returning that created map from your ``parse`` method will an event be fired by the SmartThings platform. + Only by returning that created map from your ``parse`` method will an Event be fired by the SmartThings platform. The parameters you can pass to ``createEvent`` are: *name* (required) - String - The name of the event. Typically corresponds to an attribute name of the device-handler's capabilities. + String - The name of the Event. Typically corresponds to an attribute name of the device-handler's capabilities. *value* (required) - The value of the event. The value is stored as a String, but you can pass in numbers or other objects. SmartApps will be responsible for parsing the event's value into back to its desired form (e.g., parsing a number from a string). + The value of the Event. The value is stored as a String, but you can pass in numbers or other objects. SmartApps will be responsible for parsing the Event's value into back to its desired form (e.g., parsing a number from a string) *descriptionText* - String - The description of this event. This appears in the mobile application activity feed for the device. If not specified, this will be created using the event name and value. + String - The description of this Event. This appears in the mobile application activity feed for the device. If not specified, this will be created using the Event name and value. *displayed* - boolean - ``true`` to display this event in the mobile application activity feed. ``false`` to not display this event. Defaults to ``true``. + boolean - ``true`` to display this Event in the mobile application activity feed. ``false`` to not display this Event. Defaults to ``true``. *linkText* - String - Name of the event to show in the mobile application activity feed, if specified. + String - Name of the Event to show in the mobile application activity feed, if specified. *isStateChange* - boolean - ``true`` if this event caused the device's attribute to change state. ``false`` otherwise. If not provided, ``createEvent`` will populate this based on the current state of the device. + boolean - ``true`` if this Event caused the device's attribute to change state. ``false`` otherwise. If not provided, ``createEvent`` will populate this based on the current state of the device. *unit* String - a unit string, if desired. This will be used to create the descriptionText if it (the descriptionText parameter) is not specified. Multiple Events ^^^^^^^^^^^^^^^ -You are not limited to returning a single event map from your ``parse`` method. +You are not limited to returning a single Event map from your ``parse`` method. -You can return a list of event maps to tell the SmartThings platform to generate multiple events: +You can return a list of Event maps to tell the SmartThings platform to generate multiple events: .. code-block:: groovy @@ -104,8 +104,8 @@ You can return a list of event maps to tell the SmartThings platform to generate Generating Events outside of parse ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If you need to generate an event outside of the ``parse()`` method, you can use the ``sendEvent()`` method. -It simply calls ``createEvent()`` *and* fires the event. +If you need to generate an Event outside of the ``parse()`` method, you can use the ``sendEvent()`` method. +It simply calls ``createEvent()`` *and* fires the Event. You pass in the same parameters as you do to ``createEvent()``. ---- diff --git a/device-type-developers-guide/quick-start.rst b/device-type-developers-guide/quick-start.rst index d0d6c747..afdccc95 100644 --- a/device-type-developers-guide/quick-start.rst +++ b/device-type-developers-guide/quick-start.rst @@ -72,7 +72,7 @@ From the top menu of the IDE, click on the *My Devices*. .. figure:: ../img/device-types/ide-my-devices.png Click on *+New Device* on the top-right. -This will take you to *Create Device* page. +This will take you to *Create Device* page. .. figure:: ../img/device-types/create-virtual-device.png @@ -90,16 +90,16 @@ Zigbee Id Device Network Id Should be a unique ID that identifies your Virtual Device. Make sure this ID doesn't conflict with any other device Ids. Put in "VIRTDIMMERS01". -Type - Pulldown menu lists available Device Handlers. - Note that all your custom Device Handlers are listed at the bottom of the pulldown list. +Type + Pulldown menu lists available Device Handlers. + Note that all your custom Device Handlers are listed at the bottom of the pulldown list. Scroll down the list and select the customer Device Handler that you created above. Version Option should be *Published*. Location - Must be your Hub location. + Must be your Hub Location. Hub Your Hub name associated with the above Location. @@ -120,12 +120,12 @@ You will see *virtual-dimmer-switch* device appear instantly in your SmartThings Test your Device Handler with Virtual Device -------------------------------------------- -With the Virtual Dimmer you just created you can test your Device Handler. +With the Virtual Dimmer you just created you can test your Device Handler. From your SmartThings mobile app, tap on the *OFF* tile of **virtual-dimmer-switch** to turn it *ON*. .. figure:: ../img/device-types/virtual-dimmer-on.png -Next, tap on the **virtual-dimmer-switch** to open the detail view and test the tiles. +Next, tap on the **virtual-dimmer-switch** to open the detail view and test the tiles. .. figure:: ../img/device-types/virtual-dimmer-detail.png @@ -133,7 +133,7 @@ Next, tap on the **virtual-dimmer-switch** to open the detail view and test the .. note:: - While the simulator is useful and necessary for testing how the Device Handler handles incoming messages, we recommended that you test on the mobile app with Virtual Devices wherever possible. + While the Simulator is useful and necessary for testing how the Device Handler handles incoming messages, we recommended that you test on the mobile app with Virtual Devices wherever possible. ---- diff --git a/device-type-developers-guide/simulator-metadata.rst b/device-type-developers-guide/simulator-metadata.rst index 8a99afe1..3ebe9bcc 100644 --- a/device-type-developers-guide/simulator-metadata.rst +++ b/device-type-developers-guide/simulator-metadata.rst @@ -1,27 +1,27 @@ Simulator ========= -Using the IDE simulator, we can model the behavior of the device without actually requiring a physical device. +Using the IDE Simulator, we can model the behavior of the device without actually requiring a physical device. ---- Overview -------- -On the right-hand side of the IDE, after you install a Device Handler, you'll see the simulator. -The image below is the simulator seen after installing the "Z-Wave Switch" Device Handler (available via the *Browse Device Templates* menu). +On the right-hand side of the IDE, after you install a Device Handler, you'll see the Simulator. +The image below is the Simulator seen after installing the "Z-Wave Switch" Device Handler (available via the *Browse Device Templates* menu). Go ahead, try it out. Install the Device Handler in the IDE, and choose a virtual switch. -Modify some of the simulator metadata as you read through this and see what happens. +Modify some of the Simulator metadata as you read through this and see what happens. .. figure:: ../img/device-types/simulator.png -The purpose of the simulator metadata is to model the behavior of the physical device. -Using the simulator, we can test sending messages and commands to our Device Handler. +The purpose of the Simulator metadata is to model the behavior of the physical device. +Using the Simulator, we can test sending messages and commands to our Device Handler. -There are two types of simulator declarations to define in a Device Handler - "status" and "reply". +There are two types of Simulator declarations to define in a Device Handler - "status" and "reply". ---- @@ -40,14 +40,14 @@ In the case of the Z-Wave switch, for example, we have: The key ("on" in the example above) is just a name for the action. The value ("command: 2003, payload: FF") is the message that the device will send to the Device Handler's ``parse(message)`` method when that action is taken on the physical device. -In the simulator, each status key ("on" or "off" in the example above) will be an available message in the simulator. +In the Simulator, each status key ("on" or "off" in the example above) will be an available message in the Simulator. ---- Reply ----- -The "reply" declarations specify responses that the physical device will send to the Device Handler when it receives a certain message from the hub. +The "reply" declarations specify responses that the physical device will send to the Device Handler when it receives a certain message from the Hub. For a Z-Wave switch, for example, we specify: .. code-block:: groovy @@ -85,5 +85,5 @@ But in this case it's in response to commands, not physical actuations. Summary ------- -The purpose of these declarations is to allow a virtual device to function in the IDE simulator, without being attached to a physical device. -The ``status()`` method allows us to simulate physical actuation, while the ``reply()`` method allows us to simulate sending messages to the device in response to a command from the hub. +The purpose of these declarations is to allow a virtual device to function in the IDE Simulator, without being attached to a physical device. +The ``status()`` method allows us to simulate physical actuation, while the ``reply()`` method allows us to simulate sending messages to the device in response to a command from the Hub. diff --git a/device-type-developers-guide/tiles-metadata.rst b/device-type-developers-guide/tiles-metadata.rst index 52b3ec07..02df6a80 100644 --- a/device-type-developers-guide/tiles-metadata.rst +++ b/device-type-developers-guide/tiles-metadata.rst @@ -286,7 +286,7 @@ Here's an example of using the state name as the label: state "on", label:'${name}', action:"switch.off", icon:"st.switches.switch.on", backgroundColor:"#79b821" } -When using the current attribute value, the attribute value must be set by sending an event. +When using the current attribute value, the attribute value must be set by sending an Event. For simplicity, the code examples in this documentation typically will not show the attribute value being set. Just know that if a label is set like this: @@ -297,7 +297,7 @@ Just know that if a label is set like this: state "power", label: '${currentValue} W' } -The Device Handler needs to send an event for the ``"power"`` attribute somewhere: +The Device Handler needs to send an Event for the ``"power"`` attribute somewhere: .. code-block:: groovy @@ -818,7 +818,7 @@ In order to provide the relevant data to present the label, there are four addit Value Description Notes ==================== ============================================ ================================================================================================================ ``OPERATING_STATE`` What the thermostat is doing The label will not show if ``OPERATING_STATE`` is omitted, as this is the baseline amount of meaningful information -``THERMOSTAT_MODE`` Thermostat mode (i.e. Heat, Cool, or Auto) This allows the user to know the mode (and temperature) if the system is idle (e.g. "Idle—Heat at 66°") +``THERMOSTAT_MODE`` Thermostat Mode (i.e. Heat, Cool, or Auto) This allows the user to know the Mode (and temperature) if the system is idle (e.g. "Idle—Heat at 66°") ``HEATING_SETPOINT`` At which point the system will begin heating Informs the user when heating will start (or stop, if currently heating) ``COOLING_SETPOINT`` At which point the system will begin cooling Informs the user when cooling will start (or stop, if currently cooling) ==================== ============================================ ================================================================================================================ diff --git a/device-type-developers-guide/z-wave-primer.rst b/device-type-developers-guide/z-wave-primer.rst index 7c93c9d7..000dff07 100644 --- a/device-type-developers-guide/z-wave-primer.rst +++ b/device-type-developers-guide/z-wave-primer.rst @@ -114,7 +114,7 @@ This functionality is used in a few different ways, often detailed in the device - Most door locks will send status updates to associated devices when they are locked or unlocked manually. -The SmartThings hub automatically adds itself to association group 1 when a device that supports association joins the network. +The SmartThings Hub automatically adds itself to association group 1 when a device that supports association joins the network. If this is inappropriate for your Device Handler, your Device Handler can use `AssociationRemove `__ to undo it. To associate to a group higher than 1, the Device Handler can send `AssociationSet `__. -The hub's node ID is provided to Device Handler code in the variable ``zwaveHubNodeId``. +The Hub's node ID is provided to Device Handler code in the variable ``zwaveHubNodeId``. diff --git a/device-type-developers-guide/zigbee-primer.rst b/device-type-developers-guide/zigbee-primer.rst index abeda2be..5b048f1a 100644 --- a/device-type-developers-guide/zigbee-primer.rst +++ b/device-type-developers-guide/zigbee-primer.rst @@ -143,8 +143,8 @@ Device discovery After a ZigBee device joins the network it must be queried in order to select the correct Device Handler. After a device joins (or rejoins) the network -the hub will collect the simple descriptor, manufacturer, model and application -version for each endpoint without any interaction with the cloud. The hub will +the Hub will collect the simple descriptor, manufacturer, model and application +version for each endpoint without any interaction with the cloud. The Hub will automatically resend any messages that the device does not respond to in a timely manner. Once all the information has been obtained it is sent to the cloud in the `zbjoin` message. This message is visible in Hub Events. diff --git a/getting-started/first-smartapp.rst b/getting-started/first-smartapp.rst index 49462ac8..a1c34876 100644 --- a/getting-started/first-smartapp.rst +++ b/getting-started/first-smartapp.rst @@ -22,7 +22,7 @@ At the end of this tutorial, you will know: - How to subscribe to changes in a device's state. - How to control devices. - How to schedule a SmartApp to execute in the future. -- How to use the simulator to test your SmartApp. +- How to use the Simulator to test your SmartApp. - How to publish your SmartApp and install it on your mobile phone. - :strike:`How to achieve world domination, without even trying.` @@ -46,8 +46,8 @@ Next, navigate to *My Locations* page to see the Locations you created. .. image:: ../img/getting-started/first-smartapp/my-locations.png :width: 70% -Normally you will see just one Location where you installed your Hub. -Click on the Location name appearing in the far left column (i.e., the *Name* column). You may need to log in again with your SmartThings userid and password. +Normally you will see just one Location where you installed your Hub. +Click on the Location name appearing in the far left column (i.e., the *Name* column). You may need to log in again with your SmartThings userid and password. .. warning:: @@ -115,7 +115,7 @@ In the next section we will dive into using the editor to begin writing your fir Editor ------ -Once you've created your SmartApp, you'll be taken to the editor and simulator. +Once you've created your SmartApp, you'll be taken to the editor and Simulator. Before we look at the code, it's worth becoming familiar with some of the basic features. Above the code window, there are five buttons: @@ -136,7 +136,7 @@ App Settings This takes you back to the form that you created this SmartApp from, where you can view the values entered when you created the SmartApp, as well as edit certain properties about the SmartApp. Simulator - This button toggles the display of the online simulator. We'll discuss the simulator in further detail next. + This button toggles the display of the online Simulator. We'll discuss the Simulator in further detail next. .. tip:: @@ -148,13 +148,13 @@ Simulator Simulator --------- -On the right side of the IDE is the simulator. +On the right side of the IDE is the Simulator. This is where you can install your SmartApp to test it, either using physical devices, or simulated devices. We will walk you through installing the SmartApp using this later in the tutorial. .. image:: ../img/getting-started/first-smartapp/simulator-1.png -If you don't have a location yet, the simulator will show a message instructing you to create one. Follow the steps there to create a location. +If you don't have a Location yet, the Simulator will show a message instructing you to create one. Follow the steps there to create a Location. ---- @@ -163,7 +163,7 @@ SmartApp basics The first thing to know is that there are a few different types of SmartApps. -Some SmartApps, called *Service Manager SmartApps*, manage the connection of a cloud-connected or LAN-connected device. +Some SmartApps, called *Service Manager SmartApps*, manage the connection of a Cloud-connected or LAN-connected device. *Solution Module SmartApps* provide a dashboard-like user interface in the SmartThings mobile application [1]_. @@ -174,10 +174,10 @@ This tutorial will walk you through building a simple Event-Handler SmartApp, bu Regardless of what type of SmartApp you are writing, there are a few core principles that apply to all SmartApps: -- SmartApps are not continuously running. They are executed in response to various events or schedules. -- SmartApps are installed into a user's Location, and a user may install multiple instances of a SmartApp into the same location. +- SmartApps are not continuously running. They are executed in response to various Events or schedules. +- SmartApps are installed into a user's Location, and a user may install multiple instances of a SmartApp into the same Location. - With the exception of Solution Module SmartApps, SmartApps do not have any user interface, except for the preferences page that allows the user to configure the SmartApp (more on this in a bit). -- The code that defines a SmartApp does not run on the user's mobile phone. SmartApps may execute in the SmartThings cloud, or on the hub. The mobile application uses some information from the SmartApp to drive the experience in the app. +- The code that defines a SmartApp does not run on the user's mobile phone. SmartApps may execute in the SmartThings cloud, or on the Hub. The mobile application uses some information from the SmartApp to drive the experience in the app. In your editor, you can see that there is some code already written for you. This defines the basic structure and skeleton for your SmartApp. @@ -302,7 +302,7 @@ This specifies that the user must select a device in order to install the SmartA SmartApps cannot control devices which the user did not select, and this is by design. To summarize, when the user selects and installs the SmartApp from within SmartThings mobile app, they will be prompted to select a device that supports the switch capability. -The SmartThings mobile app will provide them with a list of devices for this user's location that support the switch capability. +The SmartThings mobile app will provide them with a list of devices for this user's Location that support the switch capability. The device chosen will then be identified within the SmartApp as ``theswitch``. We covered a lot of information for such a small amount of code because it's important that you understand the importance of ``preferences`` and capabilities. @@ -319,7 +319,7 @@ Events and callback methods Our SmartApp needs to turn a switch on when motion is detected. To turn the switch on, we first need to know when motion is detected. -SmartApps can subscribe to various events so that when that event happens, the SmartApp will be notified. +SmartApps can subscribe to various Events so that when that Event happens, the SmartApp will be notified. For our SmartApp we do this by using the :ref:`smartapp_subscribe` method. In your editor, below the ``preferences``, you'll see some methods already defined: @@ -355,7 +355,7 @@ At this point, the ``updated()`` method is called. In our ``updated()`` method, notice that the first thing we do (aside from some logging, which is discussed shortly), is to call a method called :ref:`smartapp_unsubscribe`. This method is provided by the SmartThings platform, and simply removes any existing subscriptions this SmartApp has created. This is important, since the user has just changed their preferences for this SmartApp. -If we didn't do this, we might still be subscribed to events for devices that the user has removed from the SmartApp. +If we didn't do this, we might still be subscribed to Events for devices that the user has removed from the SmartApp. Also, note that both ``installed()`` and ``updated()`` call a method named ``initialize()``. Since both ``installed()`` and ``updated()`` typically both create subscriptions or schedules, we can reduce code duplication by using a helper method. @@ -368,7 +368,7 @@ Finally, note that we reference a variable named ``settings`` in our log stateme Remember the preference inputs we defined? Every preference input gets stored in a read-only map called ``settings``. We can get the values of the various inputs by indexing into the ``settings`` map with the name of the input (e.g., ``settings.theswitch``). -Now that you understand the purpose and importance of the ``installed()`` and ``updated()`` methods, we need to subscribe to any events that we are interested in. +Now that you understand the purpose and importance of the ``installed()`` and ``updated()`` methods, we need to subscribe to any Events that we are interested in. In our case, we need to know when the motion sensor reports that it detected motion. In the editor, update the ``initialize()`` method with this: @@ -379,7 +379,7 @@ In the editor, update the ``initialize()`` method with this: subscribe(themotion, "motion.active", motionDetectedHandler) } -The ``subscribe()`` method accepts three parameters: The thing we want to subscribe to (``themotion``), the specific attribute and its state we care about (``"motion.active"``), and the name of the method (``motionDetectedHandler``) that should be called when this event happens. +The ``subscribe()`` method accepts three parameters: The thing we want to subscribe to (``themotion``), the specific attribute and its state we care about (``"motion.active"``), and the name of the method (``motionDetectedHandler``) that should be called when this Event happens. How do you know what attribute and what state we can subscribe to? We refer to the :ref:`capabilities_taxonomy` to find out the available attributes the capability supports. @@ -406,7 +406,7 @@ We'll fill in the real meat of the method later. } -Every event handler method must accept a single parameter, which is an :ref:`event_ref` object that contains information about the event, such as the event's value, time it occurred, and other information. +Every event handler method must accept a single parameter, which is an :ref:`event_ref` object that contains information about the Event, such as the Event's value, time it occurred, and other information. Since we subscribed to the ``"active"`` state of the motion sensor, we know that our event handler method will only be called when the motion sensor changes from inactive to active. @@ -446,10 +446,10 @@ Click *Simulator* and you will see a Location section on the right-hand side: .. image:: ../img/getting-started/first-smartapp/ide-location.png :width: 35% -SmartApps are installed to a location in your SmartThings account. -By clicking the *Set Location* button, you are telling the simulator that you want to install this SmartApp into the chosen location. +SmartApps are installed to a Location in your SmartThings account. +By clicking the *Set Location* button, you are telling the Simulator that you want to install this SmartApp into the chosen Location. -After you have selected the location, you will see the *Preferences* section appear: +After you have selected the Location, you will see the *Preferences* section appear: .. image:: ../img/getting-started/first-smartapp/ide-devices.png :width: 35% @@ -460,9 +460,9 @@ These two inputs directly correspond to what we have in the ``preferences`` sect SmartThings will provide a "Virtual Device" when it can. When you do not have a physical device to choose from this is a very useful option. By default the virtual devices will be selected. -Click the *Install* button, and the SmartApp will be installed into the location you selected above. +Click the *Install* button, and the SmartApp will be installed into the Location you selected above. -Now we see the simulator section appear: +Now we see the Simulator section appear: .. image:: ../img/getting-started/first-smartapp/ide-simulator-unactuated.png :width: 35% @@ -480,8 +480,8 @@ You should see the switch should go on: .. warning:: - The behavior of the simulator is known to have inconsistencies. - If you are unable to see the correct device status, or unable to actuate the device, you may just be experiencing issues with the simulator. + The behavior of the Simulator is known to have inconsistencies. + If you are unable to see the correct device status, or unable to actuate the device, you may just be experiencing issues with the Simulator. In that case, just skip ahead to the next section to install the SmartApp via the SmartThings mobile app. @@ -492,7 +492,7 @@ You should see the switch should go on: Publishing and installing ------------------------- -We can now see our first SmartApp in action in the simulator. +We can now see our first SmartApp in action in the Simulator. The next question is how can we use this SmartApp on our mobile devices in the SmartThings app? To accomplish this, we need to publish the SmartApp. @@ -508,7 +508,7 @@ This means that the SmartApp will only be published for your account and not be If you have a SmartApp that you do want to publish publicly, you can do that via the "My Publication Requests" link at the top of the page. For more information on this, see :ref:`publishing-for-distribution`. -Now you should be able to see your SmartApp in the mobile app if you browse to the *My Apps* category of the marketplace: +Now you should be able to see your SmartApp in the mobile app if you browse to the *My Apps* category of the Marketplace: ================================================================== ===================================================================== .. image:: ../img/getting-started/first-smartapp/mobile-myapps.png .. image:: ../img/getting-started/first-smartapp/mobile-myfirstsmartapp.png @@ -528,12 +528,12 @@ If you have devices that support the requested capability, you'll see an option You'll also see that some other inputs were added for us. For single page preferences, every SmartApp receives an input to allow the user to assign a name of their choosing for this installation. The name that they choose will then be displayed as the name of the SmartApp. -Also by default, the user can select to only execute this SmartApp when the location is in certain :ref:`modes`. +Also by default, the user can select to only execute this SmartApp when the Location is in certain :ref:`modes`. It also includes the ability for the user to uninstall this SmartApp. .. note:: - A SmartApp may be installed into a location multiple times. + A SmartApp may be installed into a Location multiple times. For example, a person may have multiple rooms for which they want a light to come on when motion is detected. Even though the code is the same, each installation is unique, and must also be removed by the user individually. @@ -555,7 +555,7 @@ Recall that our subscription looks like this: subscribe(themotion, "motion.active", motionDetectedHandler) -We will also subscribe the ``"motion.inactive"`` event in a similar way. +We will also subscribe the ``"motion.inactive"`` Event in a similar way. Add this subscription to the ``initialize()`` method: .. code-block:: groovy @@ -568,7 +568,7 @@ Add this subscription to the ``initialize()`` method: This would then call the specified handler method when there is any reported change to the ``"motion"`` attribute. For attributes that don't have a discrete set of possible values (for example, temperature readings), this is how we subscribe to changes for that attribute. - We can then get the value of the event in the event handler by looking at the ``value`` of the passed-in Event. + We can then get the value of the Event in the event handler by looking at the ``value`` of the passed-in Event. If we were to do this in our SmartApp, it would look like this: .. code-block:: groovy @@ -596,7 +596,7 @@ We need to define the ``motionStoppedHandler`` event handler method - add this m theswitch.off() } -Save your SmartApp in the IDE, publish it again for yourself, and then install it again in the simulator. +Save your SmartApp in the IDE, publish it again for yourself, and then install it again in the Simulator. Now when you change the motion to "inactive", the switch will turn off. ---- @@ -813,7 +813,7 @@ The Device Handler will have methods defined in it that support that device. So in our case, the Device Handler for the specific switch being used will have both ``on()`` and ``off()`` methods defined. The actual implementation of these methods vary depending upon the underlying device protocols, but are typically low-level protocol-specific commands to send to the device (like Z-Wave or ZigBee). -So, when ``switch.on()`` is executed from your SmartApp, the SmartThings platform will look up the Device Handler associated with the device and call its ``on()`` method, which will in turn send the protocol and device-specific command through the hub to the device. +So, when ``switch.on()`` is executed from your SmartApp, the SmartThings platform will look up the Device Handler associated with the device and call its ``on()`` method, which will in turn send the protocol and device-specific command through the Hub to the device. Device Handlers are discussed in the :ref:`device_type_dev_guide` guide. ---- @@ -825,8 +825,8 @@ In this tutorial, you learned how to write a SmartApp. To do this, we: - Created a new SmartApp using the web-based IDE. - Defined the ``preferences`` that specifies what input we need from the user. -- Subscribed to device events and controlled a device. We used the :ref:`capabilities_taxonomy` to determine what attributes and commands a capability supports. -- Used the web-based simulator to test our SmartApp with virtual devices. +- Subscribed to device Events and controlled a device. We used the :ref:`capabilities_taxonomy` to determine what attributes and commands a capability supports. +- Used the web-based Simulator to test our SmartApp with virtual devices. - Published the SmartApp for yourself and installed it on your mobile phone. - Extended our SmartApp by allowing a user to enter the number of minutes to wait before turning the switch off, and implemented this using the ``runIn()`` method. diff --git a/getting-started/overview.rst b/getting-started/overview.rst index a11c1cc6..d6d9839b 100644 --- a/getting-started/overview.rst +++ b/getting-started/overview.rst @@ -21,7 +21,7 @@ SmartThings was built to be developer-friendly. Some of the key developer featur - A simple programming framework using the Groovy programming language. Don't know Groovy? No worries. We've written a :ref:`tutorial ` to get you up to speed. - An architecture that allows developers to control hardware with simple software. Turning a switch on is as easy as ``switch.on()``. - A web-based IDE for developing SmartThings solutions. -- A simulator for testing your code, *even if you don't have specific devices you are developing for*. +- A Simulator for testing your code, *even if you don't have specific devices you are developing for*. - An active and growing `community `__ of SmartThings developers. ---- @@ -72,7 +72,7 @@ An open platform SmartThings was built by developers, for developers. We recognized that only by creating an open development platform, will the power of the IoT be fully unleashed. -Our :ref:`web-based IDE and simulator ` allows developers to create, edit, test, and publish their SmartThings code. SmartApps and Device Handlers are hosted in our `public GitHub Repository `__, and our web-based IDE and simulator is :ref:`integrated with GitHub `. +Our :ref:`web-based IDE and simulator ` allows developers to create, edit, test, and publish their SmartThings code. SmartApps and Device Handlers are hosted in our `public GitHub Repository `__, and our web-based IDE and Simulator is :ref:`integrated with GitHub `. Our vibrant `developer community `__ is a great place to learn, collaborate, and help each other. diff --git a/getting-started/up-and-running.rst b/getting-started/up-and-running.rst index e09f096a..698c4eb6 100644 --- a/getting-started/up-and-running.rst +++ b/getting-started/up-and-running.rst @@ -5,9 +5,9 @@ Up and Running SmartThings offers a rich toolset to develop, test, and publish custom code. -Don't have a SmartThings Hub or any devices yet? Carry on! You can still create an account and even develop without any hardware, by using our online IDE and simulator. +Don't have a SmartThings Hub or any devices yet? Carry on! You can still create an account and even develop without any hardware, by using our online IDE and Simulator. -Of course, you'll want to have the hardware sooner than later, but you can start developing with SmartThings with nothing more than the free SmartThings mobile app, a web browser, and an Internet connection. +Of course, you'll want to have the hardware sooner than later, but you can start developing with SmartThings with nothing more than the free SmartThings mobile app, a web browser, and an internet connection. ---- diff --git a/latest-updates.rst b/latest-updates.rst index 3c764b87..61e14870 100644 --- a/latest-updates.rst +++ b/latest-updates.rst @@ -210,7 +210,7 @@ October 05 2016 - Updated the repository's README with pull request guidelines. - Added scheduling APIs to the :ref:`device_handler_ref` reference documentation (including all ``runEvery*`` APIs, which are now supported in Device Handlers). - Fixed broken cron tutorial link the :ref:`smartapp-scheduling` guide. -- Added note to the :ref:`first SmartApp tutorial ` and :ref:`editor_and_simulator` that the simulator is inconsistent with the mobile application. +- Added note to the :ref:`first SmartApp tutorial ` and :ref:`editor_and_simulator` that the Simulator is inconsistent with the mobile application. ---- diff --git a/ratelimits/index.rst b/ratelimits/index.rst index 72079853..4885d1f5 100644 --- a/ratelimits/index.rst +++ b/ratelimits/index.rst @@ -32,9 +32,9 @@ A SmartApp or a Device Handler is limited to no more than 250 executions in 60 s Ways to avoid hitting rate limits ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -A common cause for exceeding the 250 executions within 60 seconds limit is excessive subscriptions that might result in an infinite loop of events. For example, subscribing to an “on” and “off” event and the “on” command triggers the “off” event and vice versa - leading to a never-ending chain of event handlers being called. It is also possible that a SmartApp that subscribes to a very large number of particularly “chatty” devices may run into this limit. Making sure that your SmartApp subscriptions are not excessive in number will help avoid hitting the rate limit. +A common cause for exceeding the 250 executions within 60 seconds limit is excessive subscriptions that might result in an infinite loop of events. For example, subscribing to an “on” and “off” Event and the “on” command triggers the “off” Event and vice versa - leading to a never-ending chain of event handlers being called. It is also possible that a SmartApp that subscribes to a very large number of particularly “chatty” devices may run into this limit. Making sure that your SmartApp subscriptions are not excessive in number will help avoid hitting the rate limit. -Similarly, a Device Handler may exceed Rate Limit when it sends many commands to one device by receiving a large number of event subscriptions (if that doesn’t first hit the limit for SmartApps). For example, DLNA players that are extremely chatty, or devices that bind to frequently changing energy/power values may also encounter this limit. Ensure that your Device Handler does not issue too many commands to one single device in a single 60-second time window. +Similarly, a Device Handler may exceed Rate Limit when it sends many commands to one device by receiving a large number of Event subscriptions (if that doesn’t first hit the limit for SmartApps). For example, DLNA players that are extremely chatty, or devices that bind to frequently changing energy/power values may also encounter this limit. Ensure that your Device Handler does not issue too many commands to one single device in a single 60-second time window. ---- diff --git a/ref-docs/app-state-ref.rst b/ref-docs/app-state-ref.rst index 436c25cc..acb55751 100644 --- a/ref-docs/app-state-ref.rst +++ b/ref-docs/app-state-ref.rst @@ -33,7 +33,7 @@ The value of this Event, if the value can be parsed to a Date. .. warning:: - ``getDateValue()`` will throw an Exception if the value of the event is not parseable to a Date. + ``getDateValue()`` will throw an Exception if the value of the Event is not parseable to a Date. You should wrap calls in a try/catch block. @@ -58,13 +58,13 @@ The value of this Event, if the value can be parsed to a Date. getId() ------- -The unique system identifier for this event. +The unique system identifier for this Event. **Signature:** ``String getId()`` **Returns:** - `String`_ - the unique device identifier for this event. + `String`_ - the unique device identifier for this Event. **Example:** @@ -80,13 +80,13 @@ The unique system identifier for this event. getDescriptionText() -------------------- -The description of the event that is to be displayed to the user in the mobile application. +The description of the Event that is to be displayed to the user in the mobile application. **Signature:** ``String getDescriptionText()`` **Returns:** - `String`_ - the description of this event to be displayed to the user in the mobile application. + `String`_ - the description of this Event to be displayed to the user in the mobile application. **Example:** @@ -112,7 +112,7 @@ The value of this Event, if the value can be parsed to a Double. .. warning:: - ``getDoubleValue()`` will throw an Exception if the value of the event is not parseable to a Double. + ``getDoubleValue()`` will throw an Exception if the value of the Event is not parseable to a Double. You should wrap calls in a try/catch block. @@ -263,13 +263,13 @@ Value of the Event as a parsed JSON data structure. getLastUpdated() ---------------- -The last time this event was updated as a Date. +The last time this Event was updated as a Date. **Signature:** ``Date getLastUpdated()`` **Returns:** - `Date`_ - The last time this event was updated as a Date. + `Date`_ - The last time this Event was updated as a Date. **Example:** @@ -327,7 +327,7 @@ The name of this Event. ``String getName()`` **Returns:** - `String`_ - the name of this event. + `String`_ - the name of this Event. **Example:** @@ -349,7 +349,7 @@ The value of this Event as a Number. ``Number getNumberValue()`` **Returns:** - `Number`_ - the value of this event as a BigDecimal. + `Number`_ - the value of this Event as a BigDecimal. .. warning:: @@ -385,7 +385,7 @@ The value of this Event as a Number. ``Number getNumericValue()`` **Returns:** - `Number`_ - the value of this event as a BigDecimal. + `Number`_ - the value of this Event as a BigDecimal. .. warning:: @@ -443,7 +443,7 @@ The value of this Event as a String. ``String getValue()`` **Returns:** - `String`_ - the value of this event as a String. + `String`_ - the value of this Event as a String. **Example:** @@ -459,7 +459,7 @@ The value of this Event as a String. getXyzValue() ------------- -Value of the event as a 3-entry Map with keys 'x', 'y', and 'z' with BigDecimal values. For example: +Value of the Event as a 3-entry Map with keys 'x', 'y', and 'z' with BigDecimal values. For example: .. code-block:: groovy diff --git a/ref-docs/async-response-ref.rst b/ref-docs/async-response-ref.rst index fd48e4b2..ed37e7c5 100644 --- a/ref-docs/async-response-ref.rst +++ b/ref-docs/async-response-ref.rst @@ -40,7 +40,7 @@ Throws an exception if the request failed to get a response (e.g. Connection tim getErrorData() -------------- -In the event of an error response, returns the response body as a string. +In the Event of an error response, returns the response body as a string. Throws an exception if the response is successful and has a 2XX response. **Signature:** diff --git a/ref-docs/device-handler-ref.rst b/ref-docs/device-handler-ref.rst index f8fce597..dbfc4ab4 100644 --- a/ref-docs/device-handler-ref.rst +++ b/ref-docs/device-handler-ref.rst @@ -8,7 +8,7 @@ Device Handlers are the virtual representation of a physical device. A Device Handler defines a `metadata()`_ method that defines the device's definition, UX information, as well as how it should behave in the IDE simulator. -A Device Handler typically also defines a `parse()`_ method that is responsible for transforming raw messages from the device into events for the SmartThings platform. +A Device Handler typically also defines a `parse()`_ method that is responsible for transforming raw messages from the device into Events for the SmartThings platform. Device Handlers must also define methods for any supported commands, either through its supported capabilities, or device-specific commands. @@ -76,11 +76,11 @@ parse() This method is expected to be defined by Device Handlers. -Called when messages from a device are received from the hub. The parse method is responsible for interpreting those messages and returning :ref:`event_ref` definitions. Event definitions are maps that contain, at a minimum, name and value entries. They may also contain unit, displayText, displayed, isStateChange, and linkText entries if the default, automatically generated values of these event properties are to be overridden. See the `createEvent()`_ documentation for a description of these properties. +Called when messages from a device are received from the Hub. The parse method is responsible for interpreting those messages and returning :ref:`event_ref` definitions. Event definitions are maps that contain, at a minimum, name and value entries. They may also contain unit, displayText, displayed, isStateChange, and linkText entries if the default, automatically generated values of these Event properties are to be overridden. See the `createEvent()`_ documentation for a description of these properties. Because the ``parse()`` method is responsible for handling raw device messages, their implementations vary greatly across different Device Handlers. -The ``parse()`` method may return a map defining the :ref:`event_ref` to create and propagate through the SmartThings platform, or a list of events if multiple events should be created. It may also return a HubAction or list of HubAction objects in the case of LAN-connected devices. +The ``parse()`` method may return a map defining the :ref:`event_ref` to create and propagate through the SmartThings platform, or a list of Events if multiple Events should be created. It may also return a HubAction or list of HubAction objects in the case of LAN-connected devices. **Signature:** ``Map parse(String description)`` @@ -162,7 +162,7 @@ attribute() Called within the `definition()`_ method to declare that this Device Handler supports an attribute not defined by any of its declared capabilities. -For any supported attribute, it is expected that the Device Handler creates and sends events with the name of the attribute in the `parse()`_ method. +For any supported attribute, it is expected that the Device Handler creates and sends Events with the name of the attribute in the `parse()`_ method. **Signature:** ``void attribute(String attributeName, String attributeType [, List possibleValues])`` @@ -206,7 +206,7 @@ Called in the `definition()`_ method to define that this device supports the spe .. important:: - Whatever commands and attributes defined by that capability should be implemented by the Device Handler. For example, the "Switch" capability specifies support for the "switch" attribute and the "on" and "off" commands - any Device Handler supporting the "Switch" capability must define methods for the commands, and support the "switch" attribute by creating the appropriate events (with the name of the attribute, e.g., "switch") + Whatever commands and attributes defined by that capability should be implemented by the Device Handler. For example, the "Switch" capability specifies support for the "switch" attribute and the "on" and "off" commands - any Device Handler supporting the "Switch" capability must define methods for the commands, and support the "switch" attribute by creating the appropriate Events (with the name of the attribute, e.g., "switch") **Signature:** ``void capability(String capabilityName)`` @@ -231,7 +231,7 @@ Called in the `definition()`_ method to define that this device supports the spe } def parse(description) { - // handle device messages, determine what value of the event is + // handle device messages, determine what value of the Event is return createEvent(name: "switch", value: someValue) } @@ -397,14 +397,14 @@ Creates a Map that represents an :ref:`event_ref` object. Typically used in the ================ =========== =========== Property Type Description ================ =========== =========== - name (required) `String`_ the name of the event. Typically corresponds to an attribute name of a capability. - value (required) `Object`_ the value of the event. The value is stored as a string, but you can pass numbers or other objects. - descriptionText `String`_ the description of this event. This appears in the mobile application activity for the device. If not specified, this will be created using the event name and value. - displayed `Boolean`_ specify ``true`` to display this event in the mobile application activity feed, ``false`` to not display. Defaults to ``true``. - linkText `String`_ name of the event to show in the mobile application activity feed. - isStateChange `Boolean`_ specify ``true`` if this event caused a device attribute to change state. Typically not used, since it will be set automatically. + name (required) `String`_ the name of the Event. Typically corresponds to an attribute name of a capability. + value (required) `Object`_ the value of the Event. The value is stored as a string, but you can pass numbers or other objects. + descriptionText `String`_ the description of this Event. This appears in the mobile application activity for the device. If not specified, this will be created using the Event name and value. + displayed `Boolean`_ specify ``true`` to display this Event in the mobile application activity feed, ``false`` to not display. Defaults to ``true``. + linkText `String`_ name of the Event to show in the mobile application activity feed. + isStateChange `Boolean`_ specify ``true`` if this Event caused a device attribute to change state. Typically not used, since it will be set automatically. unit `String`_ a unit string, if desired. This will be used to create the ``descriptionText`` if it (the ``descriptionText`` option) is not specified. - data `Map`_ A map of additional information to store with the event + data `Map`_ A map of additional information to store with the Event ================ =========== =========== **Example:** @@ -544,7 +544,7 @@ At some point these will be merged, but for now the properties and methods of th fingerprint() ------------- -Called within the `definition()`_ method to define the information necessary to pair this device to the hub. +Called within the `definition()`_ method to define the information necessary to pair this device to the Hub. See the `Fingerprinting Section <../device-type-developers-guide/definition-metadata.html#fingerprinting>`__ of the Device Handler guide for more information. @@ -971,7 +971,7 @@ reply() Called in the `simulator()`_ method to model the behavior of a physical device when a virtual instance of the Device Handler is run in the IDE. -The simulator matches command strings generated by the device to those specified in the ``commandString`` argument of a reply method and, if a match is found, calls the device handler's parse method with the corresponding messageDescription. +The simulator matches command strings generated by the device to those specified in the ``commandString`` argument of a reply method and, if a match is found, calls the Device Handler's parse method with the corresponding messageDescription. For example, the reply method ``reply "2001FF,2502": "command: 2503, payload: FF"`` models the behavior of a physical Z-Wave switch in responding to an Basic Set command followed by a Switch Binary Get command. The result will be a call to the parse method with a Switch Binary Report command with a value of 255, i.e., the turning on of the switch. Modeling turn off would be done with the reply method ``reply "200100,2502": "command: 2503, payload: 00"``. @@ -1468,32 +1468,32 @@ Creates a scheduled job that calls the ``handlerMethod`` once per day at the tim sendEvent() ----------- -Create and fire an :ref:`event_ref` . Typically a Device Handler will return the map returned from `createEvent()`_ , which will allow the platform to create and fire the event. In cases where you need to fire the event (outside of the `parse()`_ method), ``sendEvent()`` is used. +Create and fire an :ref:`event_ref` . Typically a Device Handler will return the map returned from `createEvent()`_ , which will allow the platform to create and fire the Event. In cases where you need to fire the Event (outside of the `parse()`_ method), ``sendEvent()`` is used. **Signature:** ``void sendEvent(Map properties)`` **Parameters:** - `Map`_ ``properties`` - The properties of the event to create and send. + `Map`_ ``properties`` - The properties of the Event to create and send. Here are the available properties: ================ =========== Property Description ================ =========== - name (required) `String`_ - The name of the event. Typically corresponds to an attribute name of a capability. - value (required) The value of the event. The value is stored as a string, but you can pass numbers or other objects. - descriptionText `String`_ - The description of this event. This appears in the mobile application activity for the device. If not specified, this will be created using the event name and value. - displayed Pass ``true`` to display this event in the mobile application activity feed, ``false`` to not display. Defaults to ``true``. - linkText `String`_ - Name of the event to show in the mobile application activity feed. - isStateChange ``true`` if this event caused a device attribute to change state. Typically not used, since it will be set automatically. + name (required) `String`_ - The name of the Event. Typically corresponds to an attribute name of a capability. + value (required) The value of the Event. The value is stored as a string, but you can pass numbers or other objects. + descriptionText `String`_ - The description of this Event. This appears in the mobile application activity for the device. If not specified, this will be created using the Event name and value. + displayed Pass ``true`` to display this Event in the mobile application activity feed, ``false`` to not display. Defaults to ``true``. + linkText `String`_ - Name of the Event to show in the mobile application activity feed. + isStateChange ``true`` if this Event caused a device attribute to change state. Typically not used, since it will be set automatically. unit `String`_ - a unit string, if desired. This will be used to create the ``descriptionText`` if it (the ``descriptionText`` option) is not specified. - data A map of additional information to store with the event + data A map of additional information to store with the Event ================ =========== .. tip:: - Not all event properties need to be specified. ID properties like ``deviceId`` and ``locationId`` are automatically set, as are properties like ``isStateChange``, ``displayed``, and ``linkText``. + Not all Event properties need to be specified. ID properties like ``deviceId`` and ``locationId`` are automatically set, as are properties like ``isStateChange``, ``displayed``, and ``linkText``. **Returns:** void @@ -1688,7 +1688,7 @@ The status method is called in the `simulator()`_ method, and populates the sele **Parameters:** `String` ``name`` - any unique string and is used to refer to this status message in the select box. - `String` ``messageDescription`` - should be a parseable message for this Device Handler. It's passed to the Device Handler's parse method when select box entry is sent in the simulator. For example, ``status "on": "command: 2003, payload: FF"`` will send a Z-Wave Basic Report command to the device handler's parse method when the on option is selected and sent. + `String` ``messageDescription`` - should be a parseable message for this Device Handler. It's passed to the Device Handler's parse method when select box entry is sent in the simulator. For example, ``status "on": "command: 2003, payload: FF"`` will send a Z-Wave Basic Report command to the Device Handler's parse method when the on option is selected and sent. **Returns:** void diff --git a/ref-docs/device-ref.rst b/ref-docs/device-ref.rst index 2e606b5c..d3e75eb4 100644 --- a/ref-docs/device-ref.rst +++ b/ref-docs/device-ref.rst @@ -23,7 +23,7 @@ Device objects cannot be instantiated, but are created by the SmartThings platfo .. note:: - Event history is limited to the last seven days. Methods that query devices for event history will only query the last seven days. This will be called out in those methods, but is good to be generally aware of. + Event history is limited to the last seven days. Methods that query devices for Event history will only query the last seven days. This will be called out in those methods, but is good to be generally aware of. ---- @@ -281,7 +281,7 @@ Get a list of Events for the Device in reverse chronological order (newest first ======= ========== =========== **Returns:** - `List`_ <:ref:`event_ref`> - A list of events in reverse chronological order (newest first). + `List`_ <:ref:`event_ref`> - A list of Events in reverse chronological order (newest first). **Example:** @@ -299,7 +299,7 @@ Get a list of Events between the specified start and end dates. .. note:: - Only Events from the *last seven days* is query-able. Using a date range that ends more than seven days ago will return zero events. + Only Events from the *last seven days* is query-able. Using a date range that ends more than seven days ago will return zero Events. **Signature:** ``List eventsBetween(Date startDate, Date endDate [, Map options])`` @@ -345,7 +345,7 @@ Get a list of Events since the specified date. .. note:: - Only Events from the *last seven days* is query-able. Using a date range that ends more than seven days ago will return zero events. + Only Events from the *last seven days* is query-able. Using a date range that ends more than seven days ago will return zero Events. **Signature:** ``List eventsSince(Date startDate [, Map options])`` @@ -469,13 +469,13 @@ The name of the Device set by the user in the mobile application or Web IDE. getLastActivity() ----------------- -The date of the last event with a source of ``device``. (i.e. not commands) +The date of the last Event with a source of ``device``. (i.e. not commands) **Signature:** ``String getLastActivity()`` **Returns:** - `Date`_ - Date of the last event with a source of ``device``. + `Date`_ - Date of the last Event with a source of ``device``. ---- diff --git a/ref-docs/event-ref.rst b/ref-docs/event-ref.rst index 6d9f95eb..ac786fe9 100644 --- a/ref-docs/event-ref.rst +++ b/ref-docs/event-ref.rst @@ -18,17 +18,17 @@ The reference documentation here lists all methods available on an Event object getData() --------- -A map of any additional data on the event. +A map of any additional data on the Event. **Signature:** ``String getData()`` **Returns:** - `String`_ - A JSON string representing a map of the additional data (if any) on the event. + `String`_ - A JSON string representing a map of the additional data (if any) on the Event. **Example:** -Consider an event created like this: +Consider an Event created like this: .. code-block:: groovy @@ -56,7 +56,7 @@ Acquisition time of this device state record. ``Date getDate()`` **Returns:** - `Date`_ - the date and time this event record was created. + `Date`_ - the date and time this Event record was created. **Example:** @@ -73,13 +73,13 @@ Acquisition time of this device state record. getDateValue() -------------- -The value of the event as a `Date`_ object, if applicable. +The value of the Event as a `Date`_ object, if applicable. **Signature:** ``Date getDateValue()`` **Returns:** - `Date`_ - If the value of this event is date, a Date will be returned. ``null`` will be returned if the value of the event is not parseable to a Date. + `Date`_ - If the value of this Event is date, a Date will be returned. ``null`` will be returned if the value of the Event is not parseable to a Date. **Example:** @@ -117,13 +117,13 @@ The raw description that generated this Event. getDescriptionText() -------------------- -The description of the event that is to be displayed to the user in the mobile application. +The description of the Event that is to be displayed to the user in the mobile application. **Signature:** ``String getDescriptionText()`` **Returns:** - `String`_ - the description of this event to be displayed to the user in the mobile application. + `String`_ - the description of this Event to be displayed to the user in the mobile application. **Example:** @@ -157,7 +157,7 @@ getDisplayName() ``String getDisplayName()`` **Returns:** - `String`_ - The user-friendly name of the source of this event. Typically the user-assigned device label. + `String`_ - The user-friendly name of the source of this Event. Typically the user-assigned device label. **Example:** @@ -193,13 +193,13 @@ The unique system identifer of the :ref:`device_ref` associated with this Event. getId() ------- -The unique system identifier for this event. +The unique system identifier for this Event. **Signature:** ``String getId()`` **Returns:** - `String`_ - the unique device identifier for this event. + `String`_ - the unique device identifier for this Event. **Example:** @@ -226,7 +226,7 @@ The value of this Event, if the value can be parsed to a Double. .. warning:: - ``doubleValue`` will throw an Exception if the value of the event is not parseable to a Double. + ``doubleValue`` will throw an Exception if the value of the Event is not parseable to a Double. You should wrap calls in a try/catch block. @@ -420,7 +420,7 @@ getLinkText() ``getLinkText()`` is deprecated. Use :ref:`event_ref_get_display_name` instead. -The user-friendly name of the source of this event. Typically the user-assigned device label. +The user-friendly name of the source of this Event. Typically the user-assigned device label. ---- @@ -494,7 +494,7 @@ The name of this Event. ``String getName()`` **Returns:** - `String`_ - the name of this event. + `String`_ - the name of this Event. **Example:** @@ -515,7 +515,7 @@ The value of this Event as a Number. ``Number getNumberValue()`` **Returns:** - `Number`_ - the value of this event as a Number. + `Number`_ - the value of this Event as a Number. .. warning:: @@ -550,7 +550,7 @@ The value of this Event as a Number. ``Number getNumericValue()`` **Returns:** - `Number`_ - the value of this event as a Number. + `Number`_ - the value of this Event as a Number. .. warning:: @@ -590,11 +590,11 @@ The source of the Event. ================ =========== Source Description ================ =========== - `"APP"` Event originated by an app touch event in the mobile application. + `"APP"` Event originated by an app touch Event in the mobile application. `"APP_COMMAND"` Event originated by using the mobile application (for example, using the mobile application to turn a light off) `"COMMAND"` Event originated by a SmartApp or Device Handler calling a command on a device. `"DEVICE`" Event originated by the physical actuation of a device. - `"HUB"` Event originated on the hub. + `"HUB"` Event originated on the Hub. `"LOCATION"` Event originated by a Location state change (for example, sunrise and sunset events) `"USER"` ================ =========== @@ -618,7 +618,7 @@ The value of this Event as a String. ``String getStringValue()`` **Returns:** - `String`_ - the value of this event as a String. + `String`_ - the value of this Event as a String. **Example:** @@ -660,7 +660,7 @@ The value of this Event as a String. ``String getValue()`` **Returns:** - `String`_ - the value of this event as a String. + `String`_ - the value of this Event as a String. **Example:** @@ -675,7 +675,7 @@ The value of this Event as a String. getXyzValue() ------------- -Value of the event as a 3-entry Map with keys 'x', 'y', and 'z' with BigDecimal values. For example: +Value of the Event as a 3-entry Map with keys 'x', 'y', and 'z' with BigDecimal values. For example: .. code-block:: groovy diff --git a/ref-docs/hub-ref.rst b/ref-docs/hub-ref.rst index becc3132..d79b73b0 100644 --- a/ref-docs/hub-ref.rst +++ b/ref-docs/hub-ref.rst @@ -119,7 +119,7 @@ The type of the Hub. Either "PHYSICAL" or "VIRTUAL". ``String getType()`` **Returns:** - `String`_ - the type of the hub. + `String`_ - the type of the Hub. ---- diff --git a/ref-docs/hubaction-ref.rst b/ref-docs/hubaction-ref.rst index 65f4d027..c53f6fee 100644 --- a/ref-docs/hubaction-ref.rst +++ b/ref-docs/hubaction-ref.rst @@ -5,7 +5,7 @@ HubAction ========= The HubAction class is used to encapsulate a detailed request string while communicating with the devices in your network. -For example, this request string can be used for search and discovery of devices in your network. +For example, this request string can be used for search and discovery of devices in your network. HubAction can also be used in a SmartApp or in a Device Handler to communicate with the device. **Signature:** @@ -56,7 +56,7 @@ Send a device discovery command string to look for Samsung SmartCam device in yo sendHubCommand(new physicalgraph.device.HubAction("lan discovery urn:schemas-upnp-org:device:WANDevice:1", physicalgraph.device.Protocol.LAN)) .. note:: - + Typically, the device discovery is done mainly via SSDP protocol. After the device is discovered, either REST or UPnP calls can be made for verification and communication with the device. @@ -64,7 +64,7 @@ Send a device discovery command string to look for Samsung SmartCam device in yo Also note that, in the above example, while ``"urn:schemas-upnp-org:device:WANDevice:1"`` portion of the request string represents the notation defined by UPnP standard for device types, the terms ``"lan"`` and ``"discovery"`` are SmartThings-specific terms. -After the device is discovered, additional device information, such as device IP, MAC, port id, is available. +After the device is discovered, additional device information, such as device IP, MAC, port id, is available. Now it is possible to interact with the device using this additional information. Send a ``HubAction`` to the device as shown below, where myMAC is the MAC address string of the SmartCam device and ``calledBackHandler`` is the name of the method that is to be called when the device responds to this HubAction request object. @@ -95,7 +95,7 @@ Send a ``HubAction`` to the device as shown below, where myMAC is the MAC addres ``HubAction`` object. .. note:: - - A device handler's ``parse()`` method can also return a ``HubAction`` object, in adddition to the above-described usage by explicitly calling ``sendHubCommand``. - + + A Device Handler's ``parse()`` method can also return a ``HubAction`` object, in adddition to the above-described usage by explicitly calling ``sendHubCommand``. + See :ref:`building_devicetype` for more information. diff --git a/ref-docs/location-ref.rst b/ref-docs/location-ref.rst index 90abea80..38d06912 100644 --- a/ref-docs/location-ref.rst +++ b/ref-docs/location-ref.rst @@ -3,7 +3,7 @@ Location ======== -A Location represents a user's geo-location, such as "Home" or "office". Locations do not have to have a SmartThings hub, but generally do. +A Location represents a user's geo-location, such as "Home" or "office". Locations do not have to have a SmartThings Hub, but generally do. All SmartApps and Device Handlers are injected with a ``location`` property that is the Location into which the SmartApp is installed. @@ -14,13 +14,13 @@ All SmartApps and Device Handlers are injected with a ``location`` property that getContactBookEnabled() ----------------------- -``true`` if this location has contact book enabled (has contacts), ``false`` otherwise. +``true`` if this Location has Contact Book enabled (has Contacts), ``false`` otherwise. **Signature:** ``Boolean getContactBookEnabled()`` **Returns:** - ``true`` if this location has contact book enabled (has contacts), ``false`` otherwise. + ``true`` if this Location has Contact Book enabled (has Contacts), ``false`` otherwise. ---- @@ -65,7 +65,7 @@ The unique internal system identifier for the Location. getHubs() --------- -The list of Hubs for this location. Currently only Hub can be installed into a Location, thought this API returns a List to allow for future expandability. +The list of Hubs for this Location. Currently only Hub can be installed into a Location, thought this API returns a List to allow for future expandability. **Signature:** ``List getHubs()`` @@ -84,7 +84,7 @@ The list of Hubs for this location. Currently only Hub can be installed into a L getLatitude() ------------- -Geographical latitude of the location. Southern latitudes are negative. Requires that location services are enabled in the mobile app. +Geographical latitude of the Location. Southern latitudes are negative. Requires that location services are enabled in the mobile app. **Signature:** ``BigDecimal getLatitude()`` @@ -103,7 +103,7 @@ Geographical latitude of the location. Southern latitudes are negative. Requires getLongitude() -------------- -Geographical longitude of the location. Western longitudes are negative. Requires that location services are enabled in the mobile app. +Geographical longitude of the Location. Western longitudes are negative. Requires that location services are enabled in the mobile app. **Signature:** ``BigDecimal getLongitude()`` @@ -153,7 +153,7 @@ List of Modes for the Location. .. code-block:: groovy - log.debug "Modes for this location: ${location.modes}" + log.debug "Modes for this Location: ${location.modes}" ---- @@ -172,7 +172,7 @@ The name of the Location, as assigned by the user. .. code-block:: groovy - log.debug "The name of this location is: ${location.name}" + log.debug "The name of this Location is: ${location.name}" ---- @@ -181,7 +181,7 @@ The name of the Location, as assigned by the user. setMode() --------- -Set the mode for this location. +Set the mode for this Location. **Signature:** ``void setMode(String mode)`` @@ -192,7 +192,7 @@ Set the mode for this location. .. warning:: - ``setMode()`` will raise an error if the specified mode does not exist for the location. You should verify the mode exists as in the example below. + ``setMode()`` will raise an error if the specified mode does not exist for the Location. You should verify the mode exists as in the example below. **Example:** @@ -208,20 +208,20 @@ Set the mode for this location. getTemperatureScale() --------------------- -The temperature scale ("F" for fahrenheit, "C" for celsius) for this location. +The temperature scale ("F" for fahrenheit, "C" for celsius) for this Location. **Signature:** ``String getTemperatureScale()`` **Returns:** - `String`_ - the temperature scale set for this location. Either "F" for fahrenheit or "C" for celsius. + `String`_ - the temperature scale set for this Location. Either "F" for fahrenheit or "C" for celsius. **Example:** .. code-block:: groovy def tempScale = location.temperatureScale - log.debug "Temperature scale for this location is $tempScale" + log.debug "Temperature scale for this Location is $tempScale" ---- @@ -240,7 +240,7 @@ The time zone for the Location. Requires that location services are enabled in t .. code-block:: groovy - log.debug "The time zone for this location is: ${location.timeZone}" + log.debug "The time zone for this Location is: ${location.timeZone}" ---- @@ -259,7 +259,7 @@ The ZIP code for the Location, if in the USA. Requires that location services be .. code-block:: groovy - log.debug "The zip code for this location: ${location.zipCode}" + log.debug "The zip code for this Location: ${location.zipCode}" .. _BigDecimal: http://docs.oracle.com/javase/7/docs/api/java/math/BigDecimal.html diff --git a/ref-docs/mode-ref.rst b/ref-docs/mode-ref.rst index d9487379..d9c9f879 100644 --- a/ref-docs/mode-ref.rst +++ b/ref-docs/mode-ref.rst @@ -3,7 +3,7 @@ Mode ==== -Modes can be thought of as behavior filters for your home. Users want to change how things act or behave in thier home based on the mode you’re in. +Modes can be thought of as behavior filters for your home. Users want to change how things act or behave in their home based on the Mode you’re in. SmartThings developers cannot create a new Mode. The most common way to interact with a Mode instance is by using the :ref:`location_ref` to get Mode information: @@ -31,7 +31,7 @@ The unique internal system identifier of the Mode. .. code-block:: groovy def curMode = location.currentMode - log.debug "The current mode ID is: ${curMode.id}" + log.debug "The current Mode ID is: ${curMode.id}" ---- diff --git a/ref-docs/reference.rst b/ref-docs/reference.rst index 6ef7a8d7..7f5df2e2 100644 --- a/ref-docs/reference.rst +++ b/ref-docs/reference.rst @@ -50,7 +50,7 @@ Some methods may have many signatures. For example, the ``schedule`` method avai Optional parameters will be listed inside brackets (``[]``) in the method signature. -Code examples may not be executable as-is. Since SmartApps and Device Handlers execute in response to various schedules or events, and rely upon having other metdata defined, the examples have been written with brevity in mind. The code samples may need to be defined inside an event handler or otherwise executable code block to fully function. +Code examples may not be executable as-is. Since SmartApps and Device Handlers execute in response to various schedules or Events, and rely upon having other metdata defined, the examples have been written with brevity in mind. The code samples may need to be defined inside an event handler or otherwise executable code block to fully function. When appropriate, we have included various tips or warnings. In cases where an API is not adequately documented currently, we have called attention to that. We plan to add the supporting documentation soon! diff --git a/ref-docs/smartapp-ref.rst b/ref-docs/smartapp-ref.rst index dc312597..bd145203 100644 --- a/ref-docs/smartapp-ref.rst +++ b/ref-docs/smartapp-ref.rst @@ -7,7 +7,7 @@ A SmartApp is a Groovy-based program that allows developers to create automation They are created through the "New SmartApp" action in the IDE. There is no "class" for a SmartApp per se, but there are various methods and properties available to SmartApps that are documented below. -When a SmartApp executes, it executes in the context of a certain installation instance. That is, a user installs a SmartApp on their mobile application, and configures it with devices or rules unique to them. A SmartApp is not continuously running; it is executed in response to various schedules or subscribed-to events. +When a SmartApp executes, it executes in the context of a certain installation instance. That is, a user installs a SmartApp on their mobile application, and configures it with devices or rules unique to them. A SmartApp is not continuously running; it is executed in response to various schedules or subscribed-to Events. ---- @@ -22,7 +22,7 @@ installed() This method is expected to be defined by SmartApps. -Called when an instance of the app is installed. Typically subscribes to events from the configured devices and creates any scheduled jobs. +Called when an instance of the app is installed. Typically subscribes to Events from the configured devices and creates any scheduled jobs. **Signature:** ``void installed()`` @@ -52,7 +52,7 @@ updated() This method is expected to be defined by SmartApps. -Called when the preferences of an installed app are updated. Typically unsubscribes and re-subscribes to events from the configured devices and unschedules/reschedules jobs. +Called when the preferences of an installed app are updated. Typically unsubscribes and re-subscribes to Events from the configured devices and unschedules/reschedules jobs. **Signature:** ``void uninstalled()`` @@ -242,7 +242,7 @@ Adds a child device to a SmartApp. An example use is in service manager SmartApp `String`_ ``deviceNetworkId`` - the device network id of the device - ``hubId`` - *(optional)* The hub id. Defaults to ``null`` + ``hubId`` - *(optional)* The Hub id. Defaults to ``null`` `Map`_ ``properties`` *(optional)* - A map with device properties. @@ -665,9 +665,9 @@ Gets a map containing the local sunrise and sunset times. Option Description ============== =========== zipCode | `String`_ - the zip code to use for determining the times. - | If not specified then the coordinates of the hub location are used. + | If not specified then the coordinates of the Hub location are used. locationString | `String`_ - any location string supported by the Weather Underground APIs. - | If not specified then the coordinates of the hub location are used + | If not specified then the coordinates of the Hub Location are used sunriseOffset | `String`_ - adjust the sunrise time by this amount. | See `timeOffset()`_ for supported formats sunsetOffset | `String`_ - adjust the sunset time by this amount. @@ -688,7 +688,7 @@ Gets a map containing the local sunrise and sunset times. log.debug "sunrise with no parameters: ${noParams.sunrise}" log.debug "sunset with no parameters: ${noParams.sunset}" log.debug "sunrise and sunset in 90210: $beverlyHills" - log.debug "thirty minutes before sunset at current location: ${thirtyMinsBeforeSunset.sunset}" + log.debug "thirty minutes before sunset at current Location: ${thirtyMinsBeforeSunset.sunset}" ---- @@ -710,7 +710,7 @@ Calls the Weather Underground API to to return weather forecasts and related dat The weather feature to get. This corresponds to the available "Data Features" in the Weather Underground API. `String`_ ``location`` *(optional)* - The location to get the weather information for (ZIP code). If not specified, the location of the user's hub will be used. + The location to get the weather information for (ZIP code). If not specified, the Location of the user's Hub will be used. **Returns:** `Map`_ - a Map containing the weather information requested. The data returned will vary depending on the feature requested. See the Weather Underground API documentation for more information. @@ -1165,7 +1165,7 @@ Parses the specified string into an XML data structure. parseLanMessage() ----------------- -Parses a Base64-encoded LAN message received from the hub into a map with header and body elements, as well as parsing the body into an XML document. +Parses a Base64-encoded LAN message received from the Hub into a map with header and body elements, as well as parsing the body into an XML document. **Signature:** ``Map parseLanMessage(stringToParse)`` @@ -1189,7 +1189,7 @@ Parses a Base64-encoded LAN message received from the hub into a map with header parseSoapMessage() ------------------ -Parses a Base64-encoded LAN message received from the hub into a map with header and body elements, as well as parsing the body into an XML document. This method is commonly used to parse `UPNP SOAP `__ messages. +Parses a Base64-encoded LAN message received from the Hub into a map with header and body elements, as well as parsing the body into an XML document. This method is commonly used to parse `UPNP SOAP `__ messages. **Signature:** ``Map parseLanMessage(stringToParse)`` @@ -1759,11 +1759,11 @@ Creates a scheduled job that calls the ``handlerMethod`` once per day at the tim sendEvent() ----------- -Creates and sends an event constructed from the specified properties. If a device is specified, then a DEVICE event will be created, otherwise an APP event will be created. +Creates and sends an Event constructed from the specified properties. If a device is specified, then a DEVICE Event will be created, otherwise an APP Event will be created. .. note:: - SmartApps typically *respond to events*, not create them. In more rare cases, certain SmartApps or Service Manager SmartApps may have reason to send events themselves. ``sendEvent`` can be used for those cases. + SmartApps typically *respond to Events*, not create them. In more rare cases, certain SmartApps or Service Manager SmartApps may have reason to send Events themselves. ``sendEvent`` can be used for those cases. **Signature:** ``void sendEvent(Map properties)`` @@ -1771,28 +1771,28 @@ Creates and sends an event constructed from the specified properties. If a devic ``void sendEvent(Device device, Map properties)`` **Parameters:** - `Map`_ ``properties`` - The properties of the event to create and send. + `Map`_ ``properties`` - The properties of the Event to create and send. Here are the available properties: ================= =========== Property Description ================= =========== - name (required) `String`_ - The name of the event. Typically corresponds to an attribute name of a capability. - value (required) The value of the event. The value is stored as a string, but you can pass numbers or other objects. - descriptionText `String`_ - The description of this event. This appears in the mobile application activity for the device. If not specified, this will be created using the event name and value. - displayed Pass ``true`` to display this event in the mobile application activity feed, ``false`` to not display. Defaults to ``true``. - linkText `String`_ - Name of the event to show in the mobile application activity feed. - isStateChange ``true`` if this event caused a device attribute to change state. Typically not used, since it will be set automatically. + name (required) `String`_ - The name of the Event. Typically corresponds to an attribute name of a capability. + value (required) The value of the Event. The value is stored as a string, but you can pass numbers or other objects. + descriptionText `String`_ - The description of this Event. This appears in the mobile application activity for the device. If not specified, this will be created using the Event name and value. + displayed Pass ``true`` to display this Event in the mobile application activity feed, ``false`` to not display. Defaults to ``true``. + linkText `String`_ - Name of the Event to show in the mobile application activity feed. + isStateChange ``true`` if this Event caused a device attribute to change state. Typically not used, since it will be set automatically. unit `String`_ - a unit string, if desired. This will be used to create the ``descriptionText`` if it (the ``descriptionText`` option) is not specified. - :ref:`device_ref` ``device`` - The device for which this event is created for. - data A map of additional information to store with the event + :ref:`device_ref` ``device`` - The device for which this Event is created for. + data A map of additional information to store with the Event ================= =========== .. tip:: - Not all event properties need to be specified. ID properties like ``deviceId`` and ``locationId`` are automatically set, as are properties like ``isStateChange``, ``displayed``, and ``linkText``. + Not all Event properties need to be specified. ID properties like ``deviceId`` and ``locationId`` are automatically set, as are properties like ``isStateChange``, ``displayed``, and ``linkText``. **Returns:** void @@ -1855,27 +1855,27 @@ Sends a command to the Hub, with the details of the command encapsulated within sendLocationEvent() ------------------- -Sends a LOCATION event constructed from the specified properties. See the :ref:`event_ref` reference for a list of available properties. Other SmartApps can receive location events by subscribing to the location. Examples of exisisting location events include sunrise and sunset. +Sends a LOCATION Event constructed from the specified properties. See the :ref:`event_ref` reference for a list of available properties. Other SmartApps can receive Location Events by subscribing to the Location. Examples of existing Location Events include sunrise and sunset. **Signature:** ``void sendLocationEvent(Map properties)`` **Parameters:** - `Map`_ ``properties`` - The properties from which to create and send the event. + `Map`_ ``properties`` - The properties from which to create and send the Event. Here are the available properties: ================ =========== Property Description ================ =========== - name (required) `String`_ - The name of the event. Typically corresponds to an attribute name of a capability. - value (required) The value of the event. The value is stored as a string, but you can pass numbers or other objects. - descriptionText `String`_ - The description of this event. This appears in the mobile application activity for the device. If not specified, this will be created using the event name and value. - displayed Pass ``true`` to display this event in the mobile application activity feed, ``false`` to not display. Defaults to ``true``. - linkText `String`_ - Name of the event to show in the mobile application activity feed. - isStateChange ``true`` if this event caused a device attribute to change state. Typically not used, since it will be set automatically. + name (required) `String`_ - The name of the Event. Typically corresponds to an attribute name of a capability. + value (required) The value of the Event. The value is stored as a string, but you can pass numbers or other objects. + descriptionText `String`_ - The description of this Event. This appears in the mobile application activity for the device. If not specified, this will be created using the Event name and value. + displayed Pass ``true`` to display this Event in the mobile application activity feed, ``false`` to not display. Defaults to ``true``. + linkText `String`_ - Name of the Event to show in the mobile application activity feed. + isStateChange ``true`` if this Event caused a device attribute to change state. Typically not used, since it will be set automatically. unit `String`_ - a unit string, if desired. This will be used to create the ``descriptionText`` if it (the ``descriptionText`` option) is not specified. - data A map of additional information to store with the event + data A map of additional information to store with the Event ================ =========== **Returns:** @@ -2097,7 +2097,7 @@ Sends the message as an SMS message to the specified phone number but does not d setLocationMode() ----------------- -Set the mode for this location. +Set the Mode for this Location. **Signature:** ``void setLocationMode(String mode)`` @@ -2108,7 +2108,7 @@ Set the mode for this location. .. warning:: - ``setMode()`` will raise an error if the specified mode does not exist for the location. You should verify the mode exists as in the example below. + ``setMode()`` will raise an error if the specified Mode does not exist for the Location. You should verify the Mode exists as in the example below. **See Also:** :ref:`location.setMode() ` @@ -2214,9 +2214,9 @@ Parses a comma-delimited string into a map. subscribe() ----------- -Subscribes to the various events for a device or location. The specified ``handlerMethod`` will be called when the event is fired. +Subscribes to the various Events for a device or Location. The specified ``handlerMethod`` will be called when the Event is fired. -All event handler methods will be passed an :ref:`event_ref` that represents the event causing the handler method to be called. +All event handler methods will be passed an :ref:`event_ref` that represents the Event causing the handler method to be called. **Signature:** ``void subscribe(deviceOrDevices, String attributeName, handlerMethod)`` @@ -2236,11 +2236,11 @@ All event handler methods will be passed an :ref:`event_ref` that represents the `String`_ ``attributeNameAndValue`` - The specific attribute value to subscribe to, in the format ``"."`` - ``handlerMethod`` - The method to call when the event is fired. Can be a `String`_ of the method name or the method reference itself. + ``handlerMethod`` - The method to call when the Event is fired. Can be a `String`_ of the method name or the method reference itself. - :ref:`location_ref` ``location`` - The location to subscribe to + :ref:`location_ref` ``location`` - The Location to subscribe to - ``app`` - Pass in the available ``app`` property in the SmartApp to subscribe to touch events in the app. + ``app`` - Pass in the available ``app`` property in the SmartApp to subscribe to touch Events in the app. **Returns:** void @@ -2255,7 +2255,7 @@ All event handler methods will be passed an :ref:`event_ref` that represents the input "myswitches", "capability.switch", multiple: true } } - // subscribe to all state change events for ``contact`` attribute of a contact sensor + // subscribe to all state change Events for ``contact`` attribute of a contact sensor subscribe(mycontact, "contact", handlerMethod) // subscribe to all state changes for all switch devices configured @@ -2264,10 +2264,10 @@ All event handler methods will be passed an :ref:`event_ref` that represents the // subscribe to the "open" event for the contact sensor - only when the state changes to "open" will the handlerMethod be called subscribe(mycontact, "contact.open", handlerMethod) - // subscribe to all state change events for the installed SmartApp's location + // subscribe to all state change Events for the installed SmartApp's Location subscribe(location, handlerMethod) - // subscribe to touch events for this app - handlerMethod called when app is touched + // subscribe to touch Events for this app - handlerMethod called when app is touched subscribe(app, appTouchMethod) // all event handler methods must accept an event parameter @@ -2468,7 +2468,7 @@ Returns a `Date`_ of the next occurrence of the time specified in the input, rel timeZone() ---------- -Get a `TimeZone` object for the specified time value entered as a SmartApp preference. This will get the current time zone of the mobile app (not the hub location). +Get a `TimeZone` object for the specified time value entered as a SmartApp preference. This will get the current time zone of the mobile app (not the Hub Location). **Signature:** ``TimeZone timeZone(String timePreferenceString)`` diff --git a/sept-2015-faq.rst b/sept-2015-faq.rst index ae730b90..bcac7fbb 100644 --- a/sept-2015-faq.rst +++ b/sept-2015-faq.rst @@ -37,17 +37,17 @@ At some point in the future, we may create new methods that reflect the terminol Certain automations can now execute locally on the Samsung SmartThings Hub. The SmartThings internal team specifies which automations are eligible for local execution. This process requires evaluation and testing of the SmartApp and devices, as well as ensuring that the necessary code artifacts are delivered to the Hub. -Any locally executing SmartApps or Device Handlers still send events to the SmartThings cloud. This is necessary so that the mobile application can accurately reflect the current state of the devices, as well as perform any cloud-required services (e.g., sending notifications). In the event of an Internet outage, the events will be queued and sent to the SmartThings cloud when Internet is restored. +Any locally executing SmartApps or Device Handlers still send events to the SmartThings cloud. This is necessary so that the mobile application can accurately reflect the current state of the devices, as well as perform any cloud-required services (e.g., sending notifications). In the event of an internet outage, the events will be queued and sent to the SmartThings cloud when internet is restored. -It is not possible for developers to specify that certain Device Types or SmartApps execute in any particular location (cloud or on the hub). SmartApps or Device Types that have not been reviewed, tested, and delivered to the hub by the SmartThings team will execute in the SmartThings cloud. +It is not possible for developers to specify that certain Device Types or SmartApps execute in any particular location (cloud or on the Hub). SmartApps or Device Types that have not been reviewed, tested, and delivered to the Hub by the SmartThings team will execute in the SmartThings cloud. ---- -**What happens when the Internet to the Hub goes out?** +**What happens when the internet to the Hub goes out?** -Provided there is still power to the hub (wired or battery), any SmartApps that are able to execute locally will still run without an Internet connection. The mobile app will report the hub is offline, and because there are no events being sent to the SmartThings cloud, notifications will not work. +Provided there is still power to the Hub (wired or battery), any SmartApps that are able to execute locally will still run without an internet connection. The mobile app will report the Hub is offline, and because there are no events being sent to the SmartThings cloud, notifications will not work. -The radios in the hub will still function without Internet. Events to the cloud will be queued, and sent when the Internet is restored. +The radios in the Hub will still function without internet. Events to the cloud will be queued, and sent when the internet is restored. ---- diff --git a/smartapp-developers-guide/anatomy-and-life-cycle-of-a-smartapp.rst b/smartapp-developers-guide/anatomy-and-life-cycle-of-a-smartapp.rst index c6c473b8..ea4bb2bc 100644 --- a/smartapp-developers-guide/anatomy-and-life-cycle-of-a-smartapp.rst +++ b/smartapp-developers-guide/anatomy-and-life-cycle-of-a-smartapp.rst @@ -5,7 +5,7 @@ Anatomy and Life Cycle of a SmartApp SmartApps are applications that allow users to tap into the capabilities of their devices to automate their lives. -Most SmartApps are installed by the user via the SmartThings mobile client application. In addition, a few pre-installed SmartApps are readily available in the SmartThings system out-of-the-box. +Most SmartApps are installed by the user via the SmartThings mobile client application. In addition, a few pre-installed SmartApps are readily available in the SmartThings system out-of-the-box. ---- @@ -20,7 +20,7 @@ Event Handler SmartApps Event Handler SmartApps are the most common apps developed by our community. -They allow you to subscribe to events from devices and call a +They allow you to subscribe to Events from devices and call a handler method upon their firing. This method can then do a variety of things, most commonly invoking a command on another device. @@ -60,7 +60,7 @@ SmartApp structure SmartApps take the form of a single `Groovy `__ script. A typical SmartApp script is composed of four sections: *Definition*, *Preferences*, *Predefined Callbacks*, and *Event Handlers*. -There is also a *Mappings* section that is required for cloud-connected SmartApps that will be described later. +There is also a *Mappings* section that is required for Cloud-connected SmartApps that will be described later. .. image:: ../img/smartapps/demo-app.png :class: with-border @@ -87,7 +87,7 @@ The following methods, if present, are automatically called at various times dur #. ``childUninstalled()`` - Called for the parent app when a child app is uninstalled (a SmartApp can have child SmartApps). The ``installed()`` and ``updated()`` methods are commonly found in all apps. -Since the selected devices may have changed when an app is updated, both of these methods typically set up the same event subscriptions, so it is common practice to put those calls in an ``initialize()`` method and call it from both the installed and updated methods. +Since the selected devices may have changed when an app is updated, both of these methods typically set up the same Event subscriptions, so it is common practice to put those calls in an ``initialize()`` method and call it from both the installed and updated methods. The ``uninstalled()`` method is typically not needed since the system automatically removes subscriptions and schedules when a SmartApp is uninstalled. However, they can be necessary in apps that integrate with other systems and need to perform cleanup on those systems. @@ -95,7 +95,7 @@ However, they can be necessary in apps that integrate with other systems and nee Event Handlers ^^^^^^^^^^^^^^ -The remainder of the SmartApp contains the event handler methods specified in the event subscriptions and any other methods necessary for implementing the SmartApp. +The remainder of the SmartApp contains the event handler methods specified in the Event subscriptions and any other methods necessary for implementing the SmartApp. Event handler methods must have a single argument, which contains the :ref:`event_ref` object. @@ -105,14 +105,14 @@ SmartApp execution ------------------ SmartApps aren't always running. -Their various methods are executed when external events occur. -SmartApps execute when any of the following types of events occur: +Their various methods are executed when external Events occur. +SmartApps execute when any of the following types of Events occur: -1. **Pre-defined callback** - Any of the predefined lifecycle events described above occur. +1. **Pre-defined callback** - Any of the predefined lifecycle Events described above occur. 2. **Device state change** - An attribute changes on a device, which - creates an event, which triggers a subscription, which calls a + creates an Event, which triggers a subscription, which calls a handler method within your SmartApp. -3. **Location state change** - A location attribute such as *mode* changes. *Sunrise* and *sunset* are other examples of location events. +3. **Location state change** - A location attribute such as *Mode* changes. *Sunrise* and *sunset* are other examples of location events. 4. **User action on the app** - The user taps a SmartApp icon or shortcut in the mobile app UI. 5. **Scheduled event** - Using a method like runIn(), you call a method within your SmartApp at a particular time. @@ -149,21 +149,21 @@ You can find more information about SmartApp preferences `here , "", handlerMethod) -For example, to subscribe to all events from a contact sensor you would write: +For example, to subscribe to all Events from a contact sensor you would write: .. code-block:: groovy subscribe(contact1, "contact", contactHandler) The ``contactHandler()`` method would then be called whenever the sensor opened or closed. -You can also subscribe to specific event values, so to call a handler only when the contact sensor opens write: +You can also subscribe to specific Event values, so to call a handler only when the contact sensor opens write: .. code-block:: groovy @@ -171,7 +171,7 @@ You can also subscribe to specific event values, so to call a handler only when The ``subscribe()`` method call accepts either a device or a list of devices, so you don't need to explicitly iterate over each device in a list when you specify ``multiple: true`` in an input preference. -You can learn more about subscribing to device events in the :ref:`events_and_subscriptions` section. +You can learn more about subscribing to device Events in the :ref:`events_and_subscriptions` section. ---- diff --git a/smartapp-developers-guide/devices.rst b/smartapp-developers-guide/devices.rst index 109a9c3a..f7dd439c 100644 --- a/smartapp-developers-guide/devices.rst +++ b/smartapp-developers-guide/devices.rst @@ -153,7 +153,7 @@ These can be used interchangeably; they all do the same thing. Querying event history ---------------------- -To get a list of events in reverse chronological order (newest first), use the ``events()`` method: +To get a list of Events in reverse chronological order (newest first), use the ``events()`` method: .. code-block:: groovy @@ -163,7 +163,7 @@ To get a list of events in reverse chronological order (newest first), use the ` // use the max option to get more results myDevice.events(max: 30) -To get a list of events in reverse chronological order (newest first) since a given date, use the ``eventsSince`` method: +To get a list of Events in reverse chronological order (newest first) since a given date, use the ``eventsSince`` method: .. code-block:: groovy @@ -173,7 +173,7 @@ To get a list of events in reverse chronological order (newest first) since a gi // get the most recent 20 events since yesterday myDevice.eventsSince(new Date() - 1, [max: 20]) -To get a list of events between two dates, use the ``eventsBetween`` method: +To get a list of Events between two dates, use the ``eventsBetween`` method: .. code-block:: groovy diff --git a/smartapp-developers-guide/example-bon-voyage.rst b/smartapp-developers-guide/example-bon-voyage.rst index 1fd3b650..b4a3433d 100644 --- a/smartapp-developers-guide/example-bon-voyage.rst +++ b/smartapp-developers-guide/example-bon-voyage.rst @@ -10,12 +10,12 @@ Bon Voyage ---------- Our example SmartApp is fairly simple - it will monitor a set of presence -detectors, and trigger a mode change when everyone has left. +detectors, and trigger a Mode change when everyone has left. To accomplish this, our app will need to do the following: -- Gather the necessary input from the user, including which sensors to monitor, what mode to trigger, and other app preferences. -- Subscribe to the appropriate events, and take action when they are triggered. +- Gather the necessary input from the user, including which sensors to monitor, what Mode to trigger, and other app preferences. +- Subscribe to the appropriate Events, and take action when they are triggered. Let's begin with configuring the preferences. @@ -28,7 +28,7 @@ To configure the Bon Voyage app, we will want to gather the following informatio from the user: - Which sensors to monitor -- The mode to trigger when everyone is away +- The Mode to trigger when everyone is away - A false alarm threshold - Who should be notified, and how @@ -64,7 +64,7 @@ A drop down will be populated with all the devices that have the presenceSensor ``multiple: true`` allows them to add as many sensors as they'd like. Their choice(s) are then stored in a variable named ``people``. -The *Change to this mode* section allows the user to specify what mode +The *Change to this mode* section allows the user to specify what Mode should be triggered when everyone is away. The input type of ``mode`` is used, so a drop down will be populated with all the modes the user has set up. The title property is used to show the title ``"Mode?"`` above @@ -91,7 +91,7 @@ Monitor and react ----------------- Now that we have gathered the input we need from the user, we need to listen -to the appropriate events, and take action when they are triggered. +to the appropriate Events, and take action when they are triggered. We do this through the required ``installed()`` method: @@ -170,8 +170,8 @@ The first thing we need to do is see what event was triggered. We do this by inspecting the ``evt`` variable that is passed to our event handler. The presence capability can be either ``"present"`` or ``"not present"``. -Next, we check that the current mode isn't already set to the mode we -want to trigger. If we're already in our desired mode, there's nothing +Next, we check that the current Mode isn't already set to the Mode we +want to trigger. If we're already in our desired Mode, there's nothing else for us to do! Now it starts to get fun! @@ -256,8 +256,8 @@ If the time elapsed since this event exceeds our threshold, we add it to the ``a For more information about the ``findAll()`` method, or how Groovy utilizes closures, consult the Groovy documentation at http://www.groovy-lang.org/documentation.html -If the number of people away long enough equals the total number of people configured for this app, we send a message (we'll look at that method next), and then call the :ref:`smartapp_set_location_mode` method with the desired mode. -This is what will cause a mode change. +If the number of people away long enough equals the total number of people configured for this app, we send a message (we'll look at that method next), and then call the :ref:`smartapp_set_location_mode` method with the desired Mode. +This is what will cause a Mode change. The ``send()`` method takes a String parameter, ``msg``, which is the message to send. This is where our app sends a notification to any of the contacts the user has specified. diff --git a/smartapp-developers-guide/modes.rst b/smartapp-developers-guide/modes.rst index f89b7777..58db2e36 100644 --- a/smartapp-developers-guide/modes.rst +++ b/smartapp-developers-guide/modes.rst @@ -17,7 +17,7 @@ Modes can be thought of as behavior filters for the smart home. Users can change - When in "Away" mode, motion should send a text message and turn on an alarm. SmartThings comes with a few pre-configured modes, such as "Home", "Away", and "Night". -Users can also create their own modes for each location. +Users can also create their own modes for each Location. ---- @@ -39,7 +39,7 @@ You can get the current mode by using the ``mode`` or ``currentMode`` property o Getting all Modes ----------------- -You can get a list of all the modes for the location the SmartApp is installed into: +You can get a list of all the modes for the Location the SmartApp is installed into: .. code-block:: groovy @@ -51,7 +51,7 @@ You can get a list of all the modes for the location the SmartApp is installed i Setting the Mode ---------------- -You can use ``setLocationMode()`` or ``location.setMode()`` to set the mode for the location: +You can use ``setLocationMode()`` or ``location.setMode()`` to set the mode for the Location: .. code-block:: groovy @@ -61,7 +61,7 @@ You can use ``setLocationMode()`` or ``location.setMode()`` to set the mode for location.setMode("Away") -These methods will raise an error if the mode specified does not exist for the location. +These methods will raise an error if the mode specified does not exist for the Location. ---- @@ -103,7 +103,7 @@ You can listen for a mode change by subscribing to the ``"mode"`` on the ``locat log.debug "mode changed to ${evt.value}" } -In the example above ``modeChangeHandler()`` will be called whenever the mode changes for the location this SmartApp is installed into. +In the example above ``modeChangeHandler()`` will be called whenever the mode changes for the Location this SmartApp is installed into. ---- @@ -159,7 +159,7 @@ First, notice we first check if we are already in the mode specified - if we are if (location.mode != newMode) If we do need to change the mode, we first verify that the mode actually exists. -This ensures that we don't try and set the mode to one that does not exist for the location. +This ensures that we don't try and set the mode to one that does not exist for the Location. .. code-block:: groovy diff --git a/smartapp-developers-guide/parent-child-smartapps.rst b/smartapp-developers-guide/parent-child-smartapps.rst index 0044bbab..58b3bbc0 100644 --- a/smartapp-developers-guide/parent-child-smartapps.rst +++ b/smartapp-developers-guide/parent-child-smartapps.rst @@ -118,7 +118,7 @@ Children can communicate with their parent by using the ``parent`` property in t Preventing more than one parent instance ---------------------------------------- -If you want to prevent users from installing more than one parent SmartApp in their location, you can specify ``singleInstance: true`` in the definition: +If you want to prevent users from installing more than one parent SmartApp in their Location, you can specify ``singleInstance: true`` in the definition: .. code-block:: groovy @@ -421,8 +421,8 @@ Here's the child SmartApp: lights.off() } -To try it out, create the parent and child SmartApp with the code as shown above, and publish the parent SmartApp for yourself (you don't need to publish the child SmartApp, since it will be discovered by the parent and you don't want to install it individually from the marketplace). -Then, go to the marketplace and install "Simple Lighting" in "My Apps". You can then add multiple automations, with each automation being an instance of the child SmartApp ("Simple Automation"). +To try it out, create the parent and child SmartApp with the code as shown above, and publish the parent SmartApp for yourself (you don't need to publish the child SmartApp, since it will be discovered by the parent and you don't want to install it individually from the Marketplace). +Then, go to the Marketplace and install "Simple Lighting" in "My Apps". You can then add multiple automations, with each automation being an instance of the child SmartApp ("Simple Automation"). ---- diff --git a/smartapp-developers-guide/preferences-and-settings.rst b/smartapp-developers-guide/preferences-and-settings.rst index 76f412f3..3d37be95 100644 --- a/smartapp-developers-guide/preferences-and-settings.rst +++ b/smartapp-developers-guide/preferences-and-settings.rst @@ -723,7 +723,7 @@ Device Preference Input Device Name Searched For ``"device.myOnOffDevice"`` ``"My On/Off Device"`` ============================= ======================== -When using ``device.`` inputs, the platform first looks up which Device Handler it is, then finds any devices of that type for that location. +When using ``device.`` inputs, the platform first looks up which Device Handler it is, then finds any devices of that type for that Location. The algorithm searches for a Device Handler in the following order: #. A Device Handler published by SmartThings that matches the name. @@ -762,7 +762,7 @@ For example, if you have an input that prompts the user for an audio device, but Let's take a look at a few examples. Add the ``hideWhenEmpty`` attribute to SmartApp inputs to completely hide UI control if there are no devices available. -In this example, the SmartApp will not display the valve input if there were no valves in this user's location, but would display the switch input even if there were no switches. +In this example, the SmartApp will not display the valve input if there were no valves in this user's Location, but would display the switch input even if there were no switches. .. code-block:: groovy @@ -809,9 +809,9 @@ However, if both switch and valve devices are entirely absent, then the section } It is worth noting that in the last example, the audio input does not have the usual ``required: false`` attribute. -This is because the input will not be displayed if there are no audio devices associated to this location. +This is because the input will not be displayed if there are no audio devices associated to this Location. However, the SmartApp would have to be able to handle a ``null`` value for that input. -Also, it is worth remembering that if the user does have an audio device in this location, the default value of ``required: true`` will be applicable. +Also, it is worth remembering that if the user does have an audio device in this Location, the default value of ``required: true`` will be applicable. Working with other input types ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1015,7 +1015,7 @@ Next, with the ``submitOnChange`` input attribute you can also have dynamic beha dynamicPage() options ^^^^^^^^^^^^^^^^^^^^^ -Any valid option for ``page()`` will work for ``dynamicPage()`` also. +Any valid option for ``page()`` will work for ``dynamicPage()`` also. In addition, the ``refreshInterval`` input option is specific to ``dynamicPage()`` method: .. code-block:: groovy @@ -1025,7 +1025,7 @@ In addition, the ``refreshInterval`` input option is specific to ``dynamicPage() page(name: "page1") page(name: "page3") } - + ... def page1() { @@ -1033,8 +1033,8 @@ In addition, the ``refreshInterval`` input option is specific to ``dynamicPage() } *refreshInterval* - Integer - refreshes the specific page of the SmartApp on the mobile device for the integer number of seconds. - In the above example, it refreshes the *page1* every 5 seconds. + Integer - refreshes the specific page of the SmartApp on the mobile device for the integer number of seconds. + In the above example, it refreshes the *page1* every 5 seconds. ---- diff --git a/smartapp-developers-guide/routines.rst b/smartapp-developers-guide/routines.rst index f86cfafe..6202f031 100644 --- a/smartapp-developers-guide/routines.rst +++ b/smartapp-developers-guide/routines.rst @@ -23,7 +23,7 @@ Routines allow for certain things to happen whenever it executes. SmartThings co - Goodbye! - You're leaving the house - I'm Back! - You've returned to the house -Each Routine can be configured to do certain things. For example, when "I'm Back!" executes, you can set the mode to "Home", unlock doors, adjust the thermostat, etc. +Each Routine can be configured to do certain things. For example, when "I'm Back!" executes, you can set the Mode to "Home", unlock doors, adjust the thermostat, etc. Routines exist for each Location in a SmartThings account. @@ -100,7 +100,7 @@ You can then access the selected phrase like so: ---- -Routine events +Routine Events -------------- When a Routine is executed, a ``"routineExecuted"`` event is created for that Location. diff --git a/smartapp-developers-guide/scheduling.rst b/smartapp-developers-guide/scheduling.rst index 67f213a5..36ce5d0d 100644 --- a/smartapp-developers-guide/scheduling.rst +++ b/smartapp-developers-guide/scheduling.rst @@ -21,7 +21,7 @@ Broadly speaking, there are a few different ways we might want to schedule somet We'll look at each scenario in detail, and at the methods SmartThings makes available to address these requirements. .. note:: - When using the scheduler APIs, the schedule will be created using the time zone of the SmartApp's location. + When using the scheduler APIs, the schedule will be created using the time zone of the SmartApp's Location. ---- diff --git a/smartapp-developers-guide/sending-notifications.rst b/smartapp-developers-guide/sending-notifications.rst index 85e2c717..45d4461c 100644 --- a/smartapp-developers-guide/sending-notifications.rst +++ b/smartapp-developers-guide/sending-notifications.rst @@ -5,7 +5,7 @@ Sending Notifications ===================== SmartApps can send notifications, either as a push notification in the mobile app, or as SMS messages to designated recipients. -This allows SmartApps to notify people when important events happen in their home. +This allows SmartApps to notify people when important Events happen in their home. ---- @@ -17,7 +17,7 @@ Send notifications with Contact Book .. note:: The Contact Book feature is not currently enabled for users. - However, using the Contact Book APIs (with the fall-back to non-contact book features), will future-proof your SmartApp for when contact book is enabled. + However, using the Contact Book APIs (with the fall-back to non-Contact Book features), will future-proof your SmartApp for when Contact Book is enabled. See the :ref:`disabled_contact_book` section for more information. @@ -103,7 +103,7 @@ You can check the ``contactBookEnabled`` property on ``location`` to find out if .. code-block:: groovy - // check that contact book is enabled and recipients selected + // check that Contact Book is enabled and recipients selected if (location.contactBookEnabled && recipients) { sendNotificationToContacts("your message here", recipients) } else if (phone) { // check that the user did select a phone number @@ -160,10 +160,10 @@ If the user has no contacts, they can enter in a number to receive an SMS notifi def message = "The ${door.displayName} is open!" if (location.contactBookEnabled && recipients) { - log.debug "contact book enabled!" + log.debug "Contact Book enabled!" sendNotificationToContacts(message, recipients) } else { - log.debug "contact book not enabled" + log.debug "Contact Book not enabled" if (phone) { sendSms(phone, message) } @@ -316,7 +316,7 @@ Examples Several examples exist in the SmartApp templates that send notifications. Here are a few you can look at to learn more: -- `Notify Me When `__ sends push or text messages in response to a variety of events. +- `Notify Me When `__ sends push or text messages in response to a variety of Events. - `Presence Change Push `__ and `Presence Change Text `__ send notifications when people arrive or depart. ---- diff --git a/smartapp-developers-guide/simple-event-handler-smartapps.rst b/smartapp-developers-guide/simple-event-handler-smartapps.rst index 3db6f322..a4a62f5a 100644 --- a/smartapp-developers-guide/simple-event-handler-smartapps.rst +++ b/smartapp-developers-guide/simple-event-handler-smartapps.rst @@ -8,16 +8,16 @@ Turn on a light when a door opens. Turn the lights off at sunrise. Send a message if a door opens when you're not home. These are all examples of event-handler SmartApps. -They follow a common pattern - subscribe to some event, and take action when the event happens. +They follow a common pattern - subscribe to some Event, and take action when the Event happens. -This section will discuss events and how you can subscribe to them in your SmartApp. +This section will discuss Events and how you can subscribe to them in your SmartApp. ---- -Subscribe to specific device events +Subscribe to specific device Events ----------------------------------- -The most common use case for event subscriptions is for device events: +The most common use case for Event subscriptions is for device Events: .. code-block:: groovy :linenos: @@ -37,11 +37,11 @@ The most common use case for event subscriptions is for device events: log.debug "switch turned on!" } -The handler method must accept an event parameter. +The handler method must accept an Event parameter. Refer to the :ref:`event_ref` API documentation for more information about the Event object. -You can find the possible events to subscribe to by referring to the Attributes column for a capability in the :ref:`capabilities_taxonomy`. +You can find the possible Events to subscribe to by referring to the Attributes column for a capability in the :ref:`capabilities_taxonomy`. The general form we use is ".". If the attribute does not have any possible values (for example, "battery"), you would just use the attribute name. @@ -50,7 +50,7 @@ Putting these together, we use "switch.on". ---- -Subscribe to all device events +Subscribe to all device Events ------------------------------ You can also subscribe to all states by just specifying the attribute name: @@ -68,14 +68,14 @@ You can also subscribe to all states by just specifying the attribute name: } -In this case, the ``switchHandler`` method will be called for both the "on" and "off" events. +In this case, the ``switchHandler`` method will be called for both the "on" and "off" Events. ---- Subscribe to multiple devices ----------------------------- -If your SmartApp allows multiple devices, you can subscribe to events for all the devices: +If your SmartApp allows multiple devices, you can subscribe to Events for all the devices: .. code-block:: groovy @@ -95,12 +95,12 @@ If your SmartApp allows multiple devices, you can subscribe to events for all th ---- -Subscribe to Location events +Subscribe to Location Events ---------------------------- -In addition to subscribing to device events, you can also subscribe to events for the user's Location. +In addition to subscribing to device Events, you can also subscribe to Events for the user's Location. -You can subscribe to the following Location events: +You can subscribe to the following Location Events: *mode* Triggered when the mode changes. @@ -137,11 +137,11 @@ Refer to the `Sunset and Sunrise is not associated with a SmartApp in location" after selecting location +" is not associated with a SmartApp in Location" after selecting Location ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Problem - When attempting to install a Web Services SmartApp via the OAuth flow, SmartThings looks for a SmartApp published to the specific server for that location with that Client ID. + When attempting to install a Web Services SmartApp via the OAuth flow, SmartThings looks for a SmartApp published to the specific server for that Location with that Client ID. This error results from either the SmartApp not being published to the server that the user is installing into, or from trying to install a Web Services SmartApp into an account that did not publish the SmartApp. Solution If the SmartApp was self-published, make sure you are using the same account to install into (only Web Service SmartApps published by SmartThings may be installed into other user accounts). - If it is the same account, and you are trying to install into a different location, ensure the SmartApp is published on that location as well (this will require handling different OAuth Client ID and Secret). + If it is the same account, and you are trying to install into a different Location, ensure the SmartApp is published on that Location as well (this will require handling different OAuth Client ID and Secret). If this is a SmartApp published by SmartThings, contact support@smartthings.com. diff --git a/smartapp-web-services-developers-guide/tutorial-part1.rst b/smartapp-web-services-developers-guide/tutorial-part1.rst index 241ff421..63f132c7 100644 --- a/smartapp-web-services-developers-guide/tutorial-part1.rst +++ b/smartapp-web-services-developers-guide/tutorial-part1.rst @@ -54,7 +54,7 @@ The preferences definition should look like this: } Also ensure that you have an ``installed()`` and ``updated()`` method defined (this should be created by default when creating a SmartApp). -They can remain empty, since we are not subscribing to any device events in this example. +They can remain empty, since we are not subscribing to any device Events in this example. You can learn more about Web Services SmartApp preferences :ref:`here `. @@ -175,19 +175,19 @@ Publish the app for yourself, by clicking on the *Publish* button and selecting Run the SmartApp in the Simulator --------------------------------- -Using the simulator, we can quickly test our Web Services SmartApp. +Using the Simulator, we can quickly test our Web Services SmartApp. -Click the *Install* button in the simulator, select a Location to install the SmartApp into, and select a switch. +Click the *Install* button in the Simulator, select a Location to install the SmartApp into, and select a switch. -Note that in the lower right of the simulator there is an API token and an API endpoint URL: +Note that in the lower right of the Simulator there is an API token and an API endpoint URL: .. image:: ../img/smartapps/web-services/web-services-smartapp-simulator-install.png .. important:: - The base URL for of your SmartApp's API endpoint will vary depending on the location being installed into. + The base URL for of your SmartApp's API endpoint will vary depending on the Location being installed into. - **Be sure to copy the URL from the simulator to ensure you have the correct URL!** + **Be sure to copy the URL from the Simulator to ensure you have the correct URL!** We can use these to test making requests to our SmartApp. @@ -198,7 +198,7 @@ Make API calls to the SmartApp Using whatever tool you prefer for making web requests (this example will use curl, but `Apigee `__ is a good UI-based tool for making requests), we will call one of our SmartApp endpoints. -From the simulator, grab the API endpoint. It will look something like this:: +From the Simulator, grab the API endpoint. It will look something like this:: https:///api/smartapps/installations/158ef595-3695-49ab-acc1-80e93288c0c8 @@ -206,9 +206,9 @@ Your installation will have a different, unique URL. .. important:: - The base URL for of your SmartApp's API endpoint will vary depending on the location being installed into. + The base URL for of your SmartApp's API endpoint will vary depending on the Location being installed into. - **Be sure to copy the URL from the simulator to ensure you have the correct URL!** + **Be sure to copy the URL from the Simulator to ensure you have the correct URL!** To get information about the switch, we will call the /switch endpoint using a GET request. You'll need to substitute your unique endpoint and API key. @@ -236,7 +236,7 @@ Try turning the switch on and off, and then using curl to get the status, to see Uninstall the SmartApp ---------------------- -Finally, uninstall the SmartApp using the *Uninstall* button in the IDE simulator. +Finally, uninstall the SmartApp using the *Uninstall* button in the IDE Simulator. ---- @@ -244,6 +244,6 @@ Summary ------- In this tutorial, you learned how to create a SmartApp that exposes endpoints to get information about, and control, a device. -You also learned how to install the SmartApp in the simulator, and then make API calls to the endpoint. +You also learned how to install the SmartApp in the Simulator, and then make API calls to the endpoint. -In the next part of this tutorial, we'll look at how a external application might interact with SmartThings using the OAuth2 flow (instead of simply using the simulator and its generated access token). +In the next part of this tutorial, we'll look at how a external application might interact with SmartThings using the OAuth2 flow (instead of simply using the Simulator and its generated access token). diff --git a/smartapp-web-services-developers-guide/tutorial-part2.rst b/smartapp-web-services-developers-guide/tutorial-part2.rst index 9a9bd77b..3efd0fa1 100644 --- a/smartapp-web-services-developers-guide/tutorial-part2.rst +++ b/smartapp-web-services-developers-guide/tutorial-part2.rst @@ -165,8 +165,8 @@ This will be used (along with the ``client_id`` and ``client_secret``), to get t .. important:: - When you self-publish a SmartApp, it is published and available in the location that you published it. - Since SmartThings is moving into the global space, the location that you published your SmartApp corresponds to a specific server. + When you self-publish a SmartApp, it is published and available in the Location that you published it. + Since SmartThings is moving into the global space, the Location that you published your SmartApp corresponds to a specific server. This means your self-published SmartApp is only available on that server. diff --git a/tools-and-ide/account-mgmt.rst b/tools-and-ide/account-mgmt.rst index 663f5657..769520ff 100644 --- a/tools-and-ide/account-mgmt.rst +++ b/tools-and-ide/account-mgmt.rst @@ -13,7 +13,7 @@ Locations *My Locations* will show all Locations registered to your account. Choosing a particular Location will allow you to see more in depth information on that Location, including the groups created under that Location. -You can also see all events, notifications, and SmartApps under a particular Location. +You can also see all Events, notifications, and SmartApps under a particular Location. ---- @@ -24,7 +24,7 @@ Hubs :alt: My Hubs *My Hubs* will show all Hubs registered to your account. -Choosing a particular Hub will give a comprehensive look at all of the attributes of your Hub, with the opportunity to observe all events that have taken place, by clicking on *List Events*. +Choosing a particular Hub will give a comprehensive look at all of the attributes of your Hub, with the opportunity to observe all Events that have taken place, by clicking on *List Events*. You can also view all of the devices that are registered to your Hub. ---- @@ -37,7 +37,7 @@ Devices *My Devices* will show all devices attached to any of your Hubs. Choosing a particular device will give a comprehensive look at all of the -attributes of your device, with the opportunity to observe all events +attributes of your device, with the opportunity to observe all Events that have taken place, by clicking on *List Events*. ---- @@ -46,7 +46,7 @@ SmartApps --------- *My SmartApps* will show all your custom (written or edited by you) SmartApps. -You can view the SmartApp status, category, and locations from this list, as well as edit SmartApp metadata. +You can view the SmartApp status, category, and Locations from this list, as well as edit SmartApp metadata. You can click the SmartApp name to be taken to the editor where you can view and modify the code. ---- diff --git a/tools-and-ide/editor-and-simulator.rst b/tools-and-ide/editor-and-simulator.rst index 276d2b49..617b5a4e 100644 --- a/tools-and-ide/editor-and-simulator.rst +++ b/tools-and-ide/editor-and-simulator.rst @@ -89,7 +89,7 @@ The IDE simulation environment also allows you to run the simulator attached to any of the “Locations” defined within your account. When editing a SmartApp or Device Handler, you can see the simulator on the right of the page. -You can choose a location and click the *Set Location* button, and then input any preferences required by the SmartApp or Device Handler. +You can choose a Location and click the *Set Location* button, and then input any preferences required by the SmartApp or Device Handler. Click the *Install* button to run the simulator. When simulating a SmartApp, any selected devices will appear in the IDE, along with controls to actuate the devices: diff --git a/tools-and-ide/github-integration.rst b/tools-and-ide/github-integration.rst index cb358bb5..f5a33b49 100644 --- a/tools-and-ide/github-integration.rst +++ b/tools-and-ide/github-integration.rst @@ -8,7 +8,7 @@ GitHub Integration Before proceeding to enable GitHub integration in the IDE, be aware that: 1. GitHub IDE integration is not supported outside the US. - 2. GitHub IDE integration may negatively impact the performance of the IDE. + 2. GitHub IDE integration may negatively impact the performance of the IDE. As an open platform, we recognize that giving our community developers access to the repository housing our SmartApps and Device Handlers is extremely important. While you can browse the code in the IDE, not having access to the repository itself is limiting. @@ -140,7 +140,7 @@ Repository structure The repository is organized by type (SmartApps or Device Handlers) and namespace. -Each SmartApp and Device Handler should be in its own directory, named the same as the SmartApp or device handler, and appended with ``".src"``. +Each SmartApp and Device Handler should be in its own directory, named the same as the SmartApp or Device Handler, and appended with ``".src"``. For SmartApps: @@ -151,7 +151,7 @@ For Device Handlers: ``devicetypes//.src/.groovy`` The namespace is typically your GitHub user name. -When you create a SmartApp or device handler in the IDE, you provide a namespace, which is then populated in the definition method. +When you create a SmartApp or Device Handler in the IDE, you provide a namespace, which is then populated in the definition method. This namespace will be used in the directory structure as shown above. .. important:: @@ -195,7 +195,7 @@ Black Both the IDE version and repository version have been updated, and are in need of a conflict resolution. To resolve this, you should click the Update from Repo button and follow the steps there (more information about the Update from Repo action can be found below). :brown:`Brown` - Indicates that the SmartApp or device handler is unattached to the repository version. Typically this happens when a new SmartApp or device handler is created from a template, and the name or namespace hasn't been changed. If you update from the repo without changing the name or namespace, the IDE version will be replaced with the repo version. Typically in this case you would change the name and namespace to be unique for your code. + Indicates that the SmartApp or Device Handler is unattached to the repository version. Typically this happens when a new SmartApp or Device Handler is created from a template, and the name or namespace hasn't been changed. If you update from the repo without changing the name or namespace, the IDE version will be replaced with the repo version. Typically in this case you would change the name and namespace to be unique for your code. GitHub actions buttons ^^^^^^^^^^^^^^^^^^^^^^ @@ -309,7 +309,7 @@ The files you chose to update are now updated in the IDE. Commit changes in the IDE ^^^^^^^^^^^^^^^^^^^^^^^^^ -To commit changes to a SmartApp or device handler, whether it is a new file or already exists in the repository, Click on the *Commit Changes* button on the *My SmartApps* or *My device handlers* and select the repository you want to commit to. +To commit changes to a SmartApp or Device Handler, whether it is a new file or already exists in the repository, Click on the *Commit Changes* button on the *My SmartApps* or *My device handlers* and select the repository you want to commit to. In the resulting wizard, check the box next to the file you want to commit, add a commit message, and press the *Commit Changes* button.