{"_id":"582789abbe5c080f00a5a815","category":{"_id":"582789abbe5c080f00a5a7ff","version":"582789aabe5c080f00a5a7fe","project":"568bdc1483d2061900d86cdc","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-05T15:07:02.028Z","from_sync":false,"order":0,"slug":"documentation","title":"Getting Started"},"__v":0,"user":"56f0260ed386ce0e008e99da","version":{"_id":"582789aabe5c080f00a5a7fe","__v":10,"project":"568bdc1483d2061900d86cdc","createdAt":"2016-11-12T21:29:14.915Z","releaseDate":"2016-11-12T21:29:14.915Z","categories":["582789abbe5c080f00a5a7ff","582789abbe5c080f00a5a800","582789abbe5c080f00a5a801","582789abbe5c080f00a5a802","582789abbe5c080f00a5a803","582789abbe5c080f00a5a804","582789abbe5c080f00a5a805","582789abbe5c080f00a5a806","582789abbe5c080f00a5a807","582789abbe5c080f00a5a808","5827ea984ca29e0f00137a9e","583df597887db62f00644283","583df5d9c622791900e78da5","5845cd8763c11b250037967d","5845d13063c11b2500379681","5859e859e3306d1900126725","587aeb9a01cf3a0f008359eb","587c422af45e2d0f005e200d","587d84dc82f6f30f004ceee5"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"beta2","version_clean":"0.0.0","version":"0"},"parentDoc":null,"project":"568bdc1483d2061900d86cdc","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-08-24T04:02:16.624Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"Droplit.io is a cloud service that provides API-based control of connected devices. \n\nIn the next 5 minutes, you’ll learn the fundamentals by creating and controlling a virtual light:\n\n1. Make a developer account\n2. Define a _service class_\n3. Create a virtual device\n4. Assign the service class to the device\n5. Directly control in the portal and the command line\n\n\nReady… set…\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Create a portal account\"\n}\n[/block]\nGo to http://portal.droplit.io to create a free developer account and login. \n\nAssets in Droplit.io are organized into [Ecosystems](doc:ecosystems) and [Environments](doc:environments) (see also [Organization](doc:ontology)). Generally, an ecosystem represents an entire project or product line: common settings, service classes, and apps—you’ll have an ecosystem and environment automatically created when you create an account. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/f04240a-Screen_Shot_2016-08-23_at_12.00.04_AM.png\",\n        \"Screen Shot 2016-08-23 at 12.00.04 AM.png\",\n        2819,\n        1565,\n        \"#f2f2f2\"\n      ]\n    }\n  ]\n}\n[/block]\nEnvironments represents a collection of devices in a single geographical area or all devices owned by a single user. For example: if you have a smart home product that can interface with other products in the home, your product plus the other products a user owns in the same home would be contained in one Environment.\n\nYour ecosystem is an infinite canvas—as many environments, devices, and users you can imagine can fill that screen, distributed all over the world. All connected and accessible right there in that window. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Note that we have Intercom integrated with our portal; messages here go directly to our in-house crew. Response times vary by support level but are generally uber awesome fast.\",\n  \"title\": \"Having a problem?\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Define service classes\"\n}\n[/block]\nOur goal is to create and control a virtual light bulb. What do we want our virtual light to do exactly? Let’s start with the basics—we want to be able to turn it **on** and **off**, otherwise known as a switch. Device features such as a switch are defined with [Service Classes](doc:services).\n\nIn the portal, you’ll notice that you don’t have any service classes yet. That’ll change soon.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/066266a-Screen_Shot_2016-08-23_at_1.38.02_AM.png\",\n        \"Screen Shot 2016-08-23 at 1.38.02 AM.png\",\n        2821,\n        1567,\n        \"#16bd82\"\n      ]\n    }\n  ]\n}\n[/block]\n\n\n\nA service class is a template that defines a set of device capabilities with **properties**, **methods**, and **events**. A simple example is a binary switch, which is the notion of being able to turn something on and off. Take a look:\n\n\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"name\\\":\\\"BinarySwitch\\\",\\n    \\\"properties\\\": {\\n        \\\"switch\\\": {\\n            \\\"values\\\": [\\\"on\\\", \\\"off\\\"]\\n        }\\n    },\\n    \\\"methods\\\": {\\n        \\\"switchOn\\\": {\\n            \\\"description\\\": \\\"Sets switch to on\\\"\\n        },\\n        \\\"switchOff\\\": {\\n            \\\"description\\\": \\\"Sets switch to off\\\"\\n        }\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe \"properties\" field defines a property called **switch**. The property value can be one of a constrained set including *on* and *off*.\n\nThe \"methods\" field defines two methods: **switchOn** and **switchOff**. Descriptions of any member can be added using a description attribute. These descriptions are not used by the system, but are a pleasantry for the developer.\n\nAll service members must be unique within the service. For example, a service cannot have both a \"switch\" property and a \"switch\" method.\n\nGo ahead and create a **BinarySwitch** service class by copying the above JSON into the portal.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Pro tip: Watching http requests from the portal\",\n  \"body\": \"You can use [Fiddler](http://www.telerik.com/fiddler) and most modern web browsers to watch the API requests made from the portal. The portal makes calls to the same API end points that are documented here.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Create a device\"\n}\n[/block]\nNext, let’s head over to the Devices tab to make our test light. Go ahead and create a virtual device named TestLight.\n\nMake sure to set the _alias_ to `TestLight` in order for command line operations later in this walk-through to work properly.\n\nSee [Devices](doc:devices).\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/8db7f06-Screen_Shot_2016-08-23_at_12.02.47_AM.png\",\n        \"Screen Shot 2016-08-23 at 12.02.47 AM.png\",\n        2822,\n        1568,\n        \"#f4f4f4\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Assigning Service Classes\"\n}\n[/block]\nDevices are displayed with the service classes they support. Our virtual light currently does not implement any service classes. Let’s change that. \n\nYou can view details about the device by selecting the device’s card.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/3ce17d1-Screen_Shot_2016-08-23_at_1.33.58_AM.png\",\n        \"Screen Shot 2016-08-23 at 1.33.58 AM.png\",\n        2822,\n        1568,\n        \"#21b7b2\"\n      ]\n    }\n  ]\n}\n[/block]\nSelect “Add Service.” Conveniently, Service Classes you have already defined will show up in the drop down list. Go ahead and select `BinarySwitch`.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Controlling your devices\"\n}\n[/block]\nYou’re ready to control your TestLight!\n\nTo start with, try setting the value right in the portal. The session log will display any events that happen while you are on the device detail page.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/72bf4dc-Screen_Shot_2016-08-23_at_7.29.46_AM.png\",\n        \"Screen Shot 2016-08-23 at 7.29.46 AM.png\",\n        2824,\n        1565,\n        \"#22bab4\"\n      ]\n    }\n  ]\n}\n[/block]\nNow it’s time to control it through the command line. Open up a terminal. \n\n**Install Node.js**\nIf you don’t already have Nodejs installed,\nIn the terminal, from the home directory (`cd ~`), run the following commands:\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"wget https://nodejs.org/dist/v6.4.0/node-v6.4.0-linux-arm64.tar.xz\\ntar -xvf node-v6.4.0-linux-arm64.tar.xz\\ncd node-v6.4.0-linux-arm64\\nsudo cp -R * /usr/local/\\nsudo chown -R `whoami` ~/.npm\\nsudo chown -R `whoami` /usr/local/lib/node_modules\\nsudo chown -R `whoami` /usr/local\\ncd ..\\nrm –rf node-v6.4.0-linux-arm64\\nrm node-v6.4.0-linux-arm64.tar.xz\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n*This downloads, unpacks and installs NodeJs. It also fixes permission issures to allow for npm install without root permissions*\n\n**Install global NPM dependencies**\n`npm install -g ntypescript gulp typings`\n\n**If you haven’t installed the Droplit command line tools yet:**\n`npm install droplit-cli -g`\n\nLogin with: \n`droplit account authenticate`\n\nYou’ll be prompted for your Droplit.io developer account login credentials. \n\nSelect your ecosystem with:\n`droplit ecosystem select` + ecosystem ID\n(Ecosystem ID can be found in the Ecosystem tab of the portal)\n\nSelect your environment with:\n`droplit environment select` + environment ID\n(Environment ID can be found in the Environments tab of the portal)\n\nYou can see a list of the devices in the selected environment with \n\n`droplit device list`\n\nOur trusty TestLight should reveal itself. Let’s address it’s _BinarySwitch_ property:\n\n`droplit device set TestLight BinarySwitch.switch on`\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/07b1d11-Screen_Shot_2016-08-23_at_11.38.59_PM.png\",\n        \"Screen Shot 2016-08-23 at 11.38.59 PM.png\",\n        2852,\n        1566,\n        \"#17b982\"\n      ]\n    }\n  ]\n}\n[/block]\nAnd Voila! You now know how to create and control a virtual device. Virtual devices can also be controlled through API calls.\n\n**Let us know in the portal chat how long it took!**\n\nUse virtual devices to test application development with droplit.io without having to connect any physical devices to get started.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"You also can now control any physical device exactly the same way you control virtual devices.\",\n  \"title\": \"Physical devices work the same way\"\n}\n[/block]\nNow you’re ready to take control of devices in real life.\n\nIf you own:\n\n - Any of the Philips Hue ecosystem\n - Any of the Belkin WeMo devices (other than the crockpot)\n - Sonos speakers\n - LIFX smart bulbs\n - Venstar Voyager thermostat\n\nYou’ll be able to take direct control of them in the same way you just took control of your TestLight.\n\nGet started controlling devices in the real world here: https://docs.droplit.io/v0/docs/deploy-an-edge-server","excerpt":"Get the basics of controlling devices with Droplit.io in 5 minutes","slug":"creating-your-first-device","type":"basic","title":"Control your first virtual device"}

Control your first virtual device

Get the basics of controlling devices with Droplit.io in 5 minutes

Droplit.io is a cloud service that provides API-based control of connected devices. In the next 5 minutes, you’ll learn the fundamentals by creating and controlling a virtual light: 1. Make a developer account 2. Define a _service class_ 3. Create a virtual device 4. Assign the service class to the device 5. Directly control in the portal and the command line Ready… set… [block:api-header] { "type": "basic", "title": "Create a portal account" } [/block] Go to http://portal.droplit.io to create a free developer account and login. Assets in Droplit.io are organized into [Ecosystems](doc:ecosystems) and [Environments](doc:environments) (see also [Organization](doc:ontology)). Generally, an ecosystem represents an entire project or product line: common settings, service classes, and apps—you’ll have an ecosystem and environment automatically created when you create an account. [block:image] { "images": [ { "image": [ "https://files.readme.io/f04240a-Screen_Shot_2016-08-23_at_12.00.04_AM.png", "Screen Shot 2016-08-23 at 12.00.04 AM.png", 2819, 1565, "#f2f2f2" ] } ] } [/block] Environments represents a collection of devices in a single geographical area or all devices owned by a single user. For example: if you have a smart home product that can interface with other products in the home, your product plus the other products a user owns in the same home would be contained in one Environment. Your ecosystem is an infinite canvas—as many environments, devices, and users you can imagine can fill that screen, distributed all over the world. All connected and accessible right there in that window. [block:callout] { "type": "info", "body": "Note that we have Intercom integrated with our portal; messages here go directly to our in-house crew. Response times vary by support level but are generally uber awesome fast.", "title": "Having a problem?" } [/block] [block:api-header] { "type": "basic", "title": "Define service classes" } [/block] Our goal is to create and control a virtual light bulb. What do we want our virtual light to do exactly? Let’s start with the basics—we want to be able to turn it **on** and **off**, otherwise known as a switch. Device features such as a switch are defined with [Service Classes](doc:services). In the portal, you’ll notice that you don’t have any service classes yet. That’ll change soon. [block:image] { "images": [ { "image": [ "https://files.readme.io/066266a-Screen_Shot_2016-08-23_at_1.38.02_AM.png", "Screen Shot 2016-08-23 at 1.38.02 AM.png", 2821, 1567, "#16bd82" ] } ] } [/block] A service class is a template that defines a set of device capabilities with **properties**, **methods**, and **events**. A simple example is a binary switch, which is the notion of being able to turn something on and off. Take a look: [block:code] { "codes": [ { "code": "{\n \"name\":\"BinarySwitch\",\n \"properties\": {\n \"switch\": {\n \"values\": [\"on\", \"off\"]\n }\n },\n \"methods\": {\n \"switchOn\": {\n \"description\": \"Sets switch to on\"\n },\n \"switchOff\": {\n \"description\": \"Sets switch to off\"\n }\n }\n}", "language": "json" } ] } [/block] The "properties" field defines a property called **switch**. The property value can be one of a constrained set including *on* and *off*. The "methods" field defines two methods: **switchOn** and **switchOff**. Descriptions of any member can be added using a description attribute. These descriptions are not used by the system, but are a pleasantry for the developer. All service members must be unique within the service. For example, a service cannot have both a "switch" property and a "switch" method. Go ahead and create a **BinarySwitch** service class by copying the above JSON into the portal. [block:callout] { "type": "info", "title": "Pro tip: Watching http requests from the portal", "body": "You can use [Fiddler](http://www.telerik.com/fiddler) and most modern web browsers to watch the API requests made from the portal. The portal makes calls to the same API end points that are documented here." } [/block] [block:api-header] { "type": "basic", "title": "Create a device" } [/block] Next, let’s head over to the Devices tab to make our test light. Go ahead and create a virtual device named TestLight. Make sure to set the _alias_ to `TestLight` in order for command line operations later in this walk-through to work properly. See [Devices](doc:devices). [block:image] { "images": [ { "image": [ "https://files.readme.io/8db7f06-Screen_Shot_2016-08-23_at_12.02.47_AM.png", "Screen Shot 2016-08-23 at 12.02.47 AM.png", 2822, 1568, "#f4f4f4" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Assigning Service Classes" } [/block] Devices are displayed with the service classes they support. Our virtual light currently does not implement any service classes. Let’s change that. You can view details about the device by selecting the device’s card. [block:image] { "images": [ { "image": [ "https://files.readme.io/3ce17d1-Screen_Shot_2016-08-23_at_1.33.58_AM.png", "Screen Shot 2016-08-23 at 1.33.58 AM.png", 2822, 1568, "#21b7b2" ] } ] } [/block] Select “Add Service.” Conveniently, Service Classes you have already defined will show up in the drop down list. Go ahead and select `BinarySwitch`. [block:api-header] { "type": "basic", "title": "Controlling your devices" } [/block] You’re ready to control your TestLight! To start with, try setting the value right in the portal. The session log will display any events that happen while you are on the device detail page. [block:image] { "images": [ { "image": [ "https://files.readme.io/72bf4dc-Screen_Shot_2016-08-23_at_7.29.46_AM.png", "Screen Shot 2016-08-23 at 7.29.46 AM.png", 2824, 1565, "#22bab4" ] } ] } [/block] Now it’s time to control it through the command line. Open up a terminal. **Install Node.js** If you don’t already have Nodejs installed, In the terminal, from the home directory (`cd ~`), run the following commands: [block:code] { "codes": [ { "code": "wget https://nodejs.org/dist/v6.4.0/node-v6.4.0-linux-arm64.tar.xz\ntar -xvf node-v6.4.0-linux-arm64.tar.xz\ncd node-v6.4.0-linux-arm64\nsudo cp -R * /usr/local/\nsudo chown -R `whoami` ~/.npm\nsudo chown -R `whoami` /usr/local/lib/node_modules\nsudo chown -R `whoami` /usr/local\ncd ..\nrm –rf node-v6.4.0-linux-arm64\nrm node-v6.4.0-linux-arm64.tar.xz", "language": "text" } ] } [/block] *This downloads, unpacks and installs NodeJs. It also fixes permission issures to allow for npm install without root permissions* **Install global NPM dependencies** `npm install -g ntypescript gulp typings` **If you haven’t installed the Droplit command line tools yet:** `npm install droplit-cli -g` Login with: `droplit account authenticate` You’ll be prompted for your Droplit.io developer account login credentials. Select your ecosystem with: `droplit ecosystem select` + ecosystem ID (Ecosystem ID can be found in the Ecosystem tab of the portal) Select your environment with: `droplit environment select` + environment ID (Environment ID can be found in the Environments tab of the portal) You can see a list of the devices in the selected environment with `droplit device list` Our trusty TestLight should reveal itself. Let’s address it’s _BinarySwitch_ property: `droplit device set TestLight BinarySwitch.switch on` [block:image] { "images": [ { "image": [ "https://files.readme.io/07b1d11-Screen_Shot_2016-08-23_at_11.38.59_PM.png", "Screen Shot 2016-08-23 at 11.38.59 PM.png", 2852, 1566, "#17b982" ] } ] } [/block] And Voila! You now know how to create and control a virtual device. Virtual devices can also be controlled through API calls. **Let us know in the portal chat how long it took!** Use virtual devices to test application development with droplit.io without having to connect any physical devices to get started. [block:callout] { "type": "success", "body": "You also can now control any physical device exactly the same way you control virtual devices.", "title": "Physical devices work the same way" } [/block] Now you’re ready to take control of devices in real life. If you own: - Any of the Philips Hue ecosystem - Any of the Belkin WeMo devices (other than the crockpot) - Sonos speakers - LIFX smart bulbs - Venstar Voyager thermostat You’ll be able to take direct control of them in the same way you just took control of your TestLight. Get started controlling devices in the real world here: https://docs.droplit.io/v0/docs/deploy-an-edge-server