diff --git a/.gitignore b/.gitignore index 3fa29d6..c2efa4d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,2 @@ /Gemfile.lock -/_site/ +/site/ diff --git a/Gemfile b/Gemfile deleted file mode 100644 index 868915f..0000000 --- a/Gemfile +++ /dev/null @@ -1,4 +0,0 @@ -source 'https://rubygems.org' - -gem "jekyll", "~> 3.7" -gem "github-pages", group: :jekyll_plugins diff --git a/LICENSE b/LICENSE deleted file mode 100644 index a612ad9..0000000 --- a/LICENSE +++ /dev/null @@ -1,373 +0,0 @@ -Mozilla Public License Version 2.0 -================================== - -1. Definitions --------------- - -1.1. "Contributor" - means each individual or legal entity that creates, contributes to - the creation of, or owns Covered Software. - -1.2. "Contributor Version" - means the combination of the Contributions of others (if any) used - by a Contributor and that particular Contributor's Contribution. - -1.3. "Contribution" - means Covered Software of a particular Contributor. - -1.4. "Covered Software" - means Source Code Form to which the initial Contributor has attached - the notice in Exhibit A, the Executable Form of such Source Code - Form, and Modifications of such Source Code Form, in each case - including portions thereof. - -1.5. "Incompatible With Secondary Licenses" - means - - (a) that the initial Contributor has attached the notice described - in Exhibit B to the Covered Software; or - - (b) that the Covered Software was made available under the terms of - version 1.1 or earlier of the License, but not also under the - terms of a Secondary License. - -1.6. "Executable Form" - means any form of the work other than Source Code Form. - -1.7. "Larger Work" - means a work that combines Covered Software with other material, in - a separate file or files, that is not Covered Software. - -1.8. "License" - means this document. - -1.9. "Licensable" - means having the right to grant, to the maximum extent possible, - whether at the time of the initial grant or subsequently, any and - all of the rights conveyed by this License. - -1.10. "Modifications" - means any of the following: - - (a) any file in Source Code Form that results from an addition to, - deletion from, or modification of the contents of Covered - Software; or - - (b) any new file in Source Code Form that contains any Covered - Software. - -1.11. "Patent Claims" of a Contributor - means any patent claim(s), including without limitation, method, - process, and apparatus claims, in any patent Licensable by such - Contributor that would be infringed, but for the grant of the - License, by the making, using, selling, offering for sale, having - made, import, or transfer of either its Contributions or its - Contributor Version. - -1.12. "Secondary License" - means either the GNU General Public License, Version 2.0, the GNU - Lesser General Public License, Version 2.1, the GNU Affero General - Public License, Version 3.0, or any later versions of those - licenses. - -1.13. "Source Code Form" - means the form of the work preferred for making modifications. - -1.14. "You" (or "Your") - means an individual or a legal entity exercising rights under this - License. For legal entities, "You" includes any entity that - controls, is controlled by, or is under common control with You. For - purposes of this definition, "control" means (a) the power, direct - or indirect, to cause the direction or management of such entity, - whether by contract or otherwise, or (b) ownership of more than - fifty percent (50%) of the outstanding shares or beneficial - ownership of such entity. - -2. License Grants and Conditions --------------------------------- - -2.1. Grants - -Each Contributor hereby grants You a world-wide, royalty-free, -non-exclusive license: - -(a) under intellectual property rights (other than patent or trademark) - Licensable by such Contributor to use, reproduce, make available, - modify, display, perform, distribute, and otherwise exploit its - Contributions, either on an unmodified basis, with Modifications, or - as part of a Larger Work; and - -(b) under Patent Claims of such Contributor to make, use, sell, offer - for sale, have made, import, and otherwise transfer either its - Contributions or its Contributor Version. - -2.2. Effective Date - -The licenses granted in Section 2.1 with respect to any Contribution -become effective for each Contribution on the date the Contributor first -distributes such Contribution. - -2.3. Limitations on Grant Scope - -The licenses granted in this Section 2 are the only rights granted under -this License. No additional rights or licenses will be implied from the -distribution or licensing of Covered Software under this License. -Notwithstanding Section 2.1(b) above, no patent license is granted by a -Contributor: - -(a) for any code that a Contributor has removed from Covered Software; - or - -(b) for infringements caused by: (i) Your and any other third party's - modifications of Covered Software, or (ii) the combination of its - Contributions with other software (except as part of its Contributor - Version); or - -(c) under Patent Claims infringed by Covered Software in the absence of - its Contributions. - -This License does not grant any rights in the trademarks, service marks, -or logos of any Contributor (except as may be necessary to comply with -the notice requirements in Section 3.4). - -2.4. Subsequent Licenses - -No Contributor makes additional grants as a result of Your choice to -distribute the Covered Software under a subsequent version of this -License (see Section 10.2) or under the terms of a Secondary License (if -permitted under the terms of Section 3.3). - -2.5. Representation - -Each Contributor represents that the Contributor believes its -Contributions are its original creation(s) or it has sufficient rights -to grant the rights to its Contributions conveyed by this License. - -2.6. Fair Use - -This License is not intended to limit any rights You have under -applicable copyright doctrines of fair use, fair dealing, or other -equivalents. - -2.7. Conditions - -Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted -in Section 2.1. - -3. Responsibilities -------------------- - -3.1. Distribution of Source Form - -All distribution of Covered Software in Source Code Form, including any -Modifications that You create or to which You contribute, must be under -the terms of this License. You must inform recipients that the Source -Code Form of the Covered Software is governed by the terms of this -License, and how they can obtain a copy of this License. You may not -attempt to alter or restrict the recipients' rights in the Source Code -Form. - -3.2. Distribution of Executable Form - -If You distribute Covered Software in Executable Form then: - -(a) such Covered Software must also be made available in Source Code - Form, as described in Section 3.1, and You must inform recipients of - the Executable Form how they can obtain a copy of such Source Code - Form by reasonable means in a timely manner, at a charge no more - than the cost of distribution to the recipient; and - -(b) You may distribute such Executable Form under the terms of this - License, or sublicense it under different terms, provided that the - license for the Executable Form does not attempt to limit or alter - the recipients' rights in the Source Code Form under this License. - -3.3. Distribution of a Larger Work - -You may create and distribute a Larger Work under terms of Your choice, -provided that You also comply with the requirements of this License for -the Covered Software. If the Larger Work is a combination of Covered -Software with a work governed by one or more Secondary Licenses, and the -Covered Software is not Incompatible With Secondary Licenses, this -License permits You to additionally distribute such Covered Software -under the terms of such Secondary License(s), so that the recipient of -the Larger Work may, at their option, further distribute the Covered -Software under the terms of either this License or such Secondary -License(s). - -3.4. Notices - -You may not remove or alter the substance of any license notices -(including copyright notices, patent notices, disclaimers of warranty, -or limitations of liability) contained within the Source Code Form of -the Covered Software, except that You may alter any license notices to -the extent required to remedy known factual inaccuracies. - -3.5. Application of Additional Terms - -You may choose to offer, and to charge a fee for, warranty, support, -indemnity or liability obligations to one or more recipients of Covered -Software. However, You may do so only on Your own behalf, and not on -behalf of any Contributor. You must make it absolutely clear that any -such warranty, support, indemnity, or liability obligation is offered by -You alone, and You hereby agree to indemnify every Contributor for any -liability incurred by such Contributor as a result of warranty, support, -indemnity or liability terms You offer. You may include additional -disclaimers of warranty and limitations of liability specific to any -jurisdiction. - -4. Inability to Comply Due to Statute or Regulation ---------------------------------------------------- - -If it is impossible for You to comply with any of the terms of this -License with respect to some or all of the Covered Software due to -statute, judicial order, or regulation then You must: (a) comply with -the terms of this License to the maximum extent possible; and (b) -describe the limitations and the code they affect. Such description must -be placed in a text file included with all distributions of the Covered -Software under this License. Except to the extent prohibited by statute -or regulation, such description must be sufficiently detailed for a -recipient of ordinary skill to be able to understand it. - -5. Termination --------------- - -5.1. The rights granted under this License will terminate automatically -if You fail to comply with any of its terms. However, if You become -compliant, then the rights granted under this License from a particular -Contributor are reinstated (a) provisionally, unless and until such -Contributor explicitly and finally terminates Your grants, and (b) on an -ongoing basis, if such Contributor fails to notify You of the -non-compliance by some reasonable means prior to 60 days after You have -come back into compliance. Moreover, Your grants from a particular -Contributor are reinstated on an ongoing basis if such Contributor -notifies You of the non-compliance by some reasonable means, this is the -first time You have received notice of non-compliance with this License -from such Contributor, and You become compliant prior to 30 days after -Your receipt of the notice. - -5.2. If You initiate litigation against any entity by asserting a patent -infringement claim (excluding declaratory judgment actions, -counter-claims, and cross-claims) alleging that a Contributor Version -directly or indirectly infringes any patent, then the rights granted to -You by any and all Contributors for the Covered Software under Section -2.1 of this License shall terminate. - -5.3. In the event of termination under Sections 5.1 or 5.2 above, all -end user license agreements (excluding distributors and resellers) which -have been validly granted by You or Your distributors under this License -prior to termination shall survive termination. - -************************************************************************ -* * -* 6. Disclaimer of Warranty * -* ------------------------- * -* * -* Covered Software is provided under this License on an "as is" * -* basis, without warranty of any kind, either expressed, implied, or * -* statutory, including, without limitation, warranties that the * -* Covered Software is free of defects, merchantable, fit for a * -* particular purpose or non-infringing. The entire risk as to the * -* quality and performance of the Covered Software is with You. * -* Should any Covered Software prove defective in any respect, You * -* (not any Contributor) assume the cost of any necessary servicing, * -* repair, or correction. This disclaimer of warranty constitutes an * -* essential part of this License. No use of any Covered Software is * -* authorized under this License except under this disclaimer. * -* * -************************************************************************ - -************************************************************************ -* * -* 7. Limitation of Liability * -* -------------------------- * -* * -* Under no circumstances and under no legal theory, whether tort * -* (including negligence), contract, or otherwise, shall any * -* Contributor, or anyone who distributes Covered Software as * -* permitted above, be liable to You for any direct, indirect, * -* special, incidental, or consequential damages of any character * -* including, without limitation, damages for lost profits, loss of * -* goodwill, work stoppage, computer failure or malfunction, or any * -* and all other commercial damages or losses, even if such party * -* shall have been informed of the possibility of such damages. This * -* limitation of liability shall not apply to liability for death or * -* personal injury resulting from such party's negligence to the * -* extent applicable law prohibits such limitation. Some * -* jurisdictions do not allow the exclusion or limitation of * -* incidental or consequential damages, so this exclusion and * -* limitation may not apply to You. * -* * -************************************************************************ - -8. Litigation -------------- - -Any litigation relating to this License may be brought only in the -courts of a jurisdiction where the defendant maintains its principal -place of business and such litigation shall be governed by laws of that -jurisdiction, without reference to its conflict-of-law provisions. -Nothing in this Section shall prevent a party's ability to bring -cross-claims or counter-claims. - -9. Miscellaneous ----------------- - -This License represents the complete agreement concerning the subject -matter hereof. If any provision of this License is held to be -unenforceable, such provision shall be reformed only to the extent -necessary to make it enforceable. Any law or regulation which provides -that the language of a contract shall be construed against the drafter -shall not be used to construe this License against a Contributor. - -10. Versions of the License ---------------------------- - -10.1. New Versions - -Mozilla Foundation is the license steward. Except as provided in Section -10.3, no one other than the license steward has the right to modify or -publish new versions of this License. Each version will be given a -distinguishing version number. - -10.2. Effect of New Versions - -You may distribute the Covered Software under the terms of the version -of the License under which You originally received the Covered Software, -or under the terms of any subsequent version published by the license -steward. - -10.3. Modified Versions - -If you create software not governed by this License, and you want to -create a new license for such software, you may create and use a -modified version of this License if you rename the license and remove -any references to the name of the license steward (except to note that -such modified license differs from this License). - -10.4. Distributing Source Code Form that is Incompatible With Secondary -Licenses - -If You choose to distribute Source Code Form that is Incompatible With -Secondary Licenses under the terms of this version of the License, the -notice described in Exhibit B of this License must be attached. - -Exhibit A - Source Code Form License Notice -------------------------------------------- - - This Source Code Form is subject to the terms of the Mozilla Public - License, v. 2.0. If a copy of the MPL was not distributed with this - file, You can obtain one at http://mozilla.org/MPL/2.0/. - -If it is not possible or desirable to put the notice in a particular -file, then You may include the notice in a location (such as a LICENSE -file in a relevant directory) where a recipient would be likely to look -for such a notice. - -You may add additional accurate notices of copyright ownership. - -Exhibit B - "Incompatible With Secondary Licenses" Notice ---------------------------------------------------------- - - This Source Code Form is "Incompatible With Secondary Licenses", as - defined by the Mozilla Public License, v. 2.0. diff --git a/README.md b/README.md index 4776451..f680962 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,17 @@ -# WebThings +# WebThings Documentation -[WebThings](https://webthings.io/) is an open platform for monitoring and controlling devices over the web. +This is the source code of the documentation for the [WebThings](https://webthings.io) software platform. -It is an open source implementation of emerging [Web of Things](https://www.w3.org/WoT/) standards at the W3C. +To generate a local copy: -## User Guide -### WebThings Gateway -[WebThings Gateway](https://webthings.io/gateway/) is a software distribution for smart home gateways which allows users to directly monitor and control their smart home over the web, without a middleman. -* [Getting Started Guide - Raspberry Pi](./gateway-getting-started-guide.md) -* [Getting Started Guide - Docker](https://github.com/WebThingsIO/gateway-docker/blob/master/README.md) -* [User Guide](./gateway-user-guide.md) -* [Supported Hardware](https://github.com/WebThingsIO/wiki/wiki/Supported-Hardware) +- [Install](https://www.mkdocs.org/user-guide/installation/) MkDocs -#### Tips -* [Pairing SmartThings sensors](https://github.com/WebThingsIO/wiki/wiki/Pairing-SmartThings-sensors) -* [Configuring the Arlec Smart Plug](https://github.com/WebThingsIO/wiki/wiki/Arlec-Smart-Plug) -* [Factory reset a Cree Connected bulb](https://github.com/WebThingsIO/wiki/wiki/HOWTO%3A-Factory-reset-a-Cree-Connected-bulb) -* [Factory reset a Hue bulb](https://github.com/WebThingsIO/wiki/wiki/HOWTO%3A-Factory-reset-a-Hue-bulb) -* [Factory reset a Hue Wireless Dimmer](https://github.com/WebThingsIO/wiki/wiki/HOWTO%3A-Factory-reset-a-Hue-Wireless-Dimmer) -* [Factory reset an IKEA bulb](https://github.com/WebThingsIO/wiki/wiki/HOWTO%3A-Factory-reset-an-IKEA-bulb) +`$ pip install mkdocs` -## Developer Guide +- Serve the docs locally -### Web Thing API -The Web Thing API is the REST & WebSockets API used by the WebThings IoT platform for monitoring and controlling devices over the web. Parts of the Web Thing API specification are currently being standardised via the W3C. -* [Introduction to the Web Thing API](https://github.com/WebThingsIO/wot/blob/gh-pages/README.md) -* [Web Thing API specification](https://webthings.io/api/) - * [Examples using curl](https://github.com/WebThingsIO/curl-examples/blob/master/README.md) - * [Differences with W3C specification](https://github.com/webthingsio/wiki/wiki/Mozilla-W3C-Differences) -* [WoT Capability Schemas](https://webthings.io/schemas/) +`$ mkdocs serve` -### WebThings Gateway -[WebThings Gateway](https://webthings.io/gateway/) is an open source implementation of a Web of Things gateway which bridges a range of different IoT protocols to the Web Thing API and provides a web interface for users to monitor and control devices. -* [Gateway Architecture](https://github.com/WebThingsIO/wiki/wiki/Gateway-Architecture) -* [Build Instructions](https://github.com/WebThingsIO/gateway#readme) -* [Creating a new translation](https://github.com/WebThingsIO/wiki/wiki/Fluent%3A-Making-a-new-translation) -* [Testing pre-release OTA updates](https://github.com/WebThingsIO/wiki/wiki/Testing-prerelease-OTA-updates) -* [Releasing a Gateway OTA Update](https://github.com/WebThingsIO/wiki/wiki/How-To-Release-a-Gateway-OTA-Update) +You should then be able to access the docs at http://127.0.0.1:8000/ and they will live reload as you edit the markdown files. -#### Add-Ons -* [Introduction to Add-ons](https://github.com/WebThingsIO/addon-list/blob/master/guidelines.md) -* [Creating an Add-on](https://github.com/WebThingsIO/wiki/wiki/HOWTO%3A-Create-an-add-on) -* [Configuring an Add-on](https://github.com/WebThingsIO/wiki/wiki/Add-on-Configuration) -* [Publishing an Add-on](https://github.com/WebThingsIO/addon-list#readme) -* Examples: - * [Adapter Add-on](https://github.com/WebThingsIO/example-adapter) - * [Notifier Add-on](https://github.com/WebThingsIO/example-notifier) - * [Extension Add-on](https://github.com/WebThingsIO/example-extension) -* Add-on APIs - * [Node.js Add-on API](https://github.com/WebThingsIO/gateway-addon-node) - * [Python Add-on API](https://github.com/WebThingsIO/gateway-addon-python) -* [Adapter Inter-process communication](https://github.com/WebThingsIO/wiki/wiki/Adapter-IPC) -* [Debug Controller](https://github.com/WebThingsIO/wiki/wiki/Using-the-debug-controller) - -### WebThings Framework -[WebThings Framework](https://webthings.io/framework/) is a collection of re-usable software components to help developers build their own web things which directly expose the Web Thing API. - -#### WebThings Libraries -* [Node.js](https://github.com/WebThingsIO/webthing-node) -* [Python](https://github.com/WebThingsIO/webthing-python) -* [Java](https://github.com/WebThingsIO/webthing-java) -* [Rust](https://github.com/WebThingsIO/webthing-rust) -* [Arduino](https://github.com/WebThingsIO/webthing-arduino) -* [MicroPython](https://github.com/WebThingsIO/webthing-upy) - -#### Third Party Libraries -* [Moddable](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/webthings.md) -* [Atmosphere IoT](https://developer.atmosphereiot.com/documents/guides/gettingstartedwebthings.html) -* [IoT.js](https://github.com/rzr/webthing-iotjs) by rzr -* [C#](https://github.com/lillo42/webthing-csharp) by lillo42 -* [Go](https://github.com/rzr/webthing-go) by rzr -* [Go](https://github.com/dravenk/webthing-go) by dravenk -* [ESP-IDF](https://github.com/akshayvernekar/esp-webthing) by akshayvernekar -* [PHP](https://github.com/maliknaik16/webthing-php) by maliknaik16 -* [Python](https://github.com/hidaris/aiowebthing) by hidaris - -### WebThings Cloud -WebThings Cloud is a collection of cloud services for remotely managing web things over the internet. WebThings Cloud includes a remote access service which can create an end-to-end encrypted tunnel between a WoT gateway (or device) and a WoT client so that it can be securely accessed over the internet. -* [How Remote Access Works](https://github.com/WebThingsIO/registration_server/blob/master/doc/flow.md) -* [Registration Server API](https://github.com/WebThingsIO/registration_server/blob/master/doc/api.md) - -### Tips -* [Glossary of Terms](https://github.com/WebThingsIO/wiki/wiki/Glossary-of-Terms) -* [Installing Node.js](https://github.com/WebThingsIO/wiki/wiki/Installing-Node.js) -* [Accessing the command line on the Raspberry Pi](https://github.com/WebThingsIO/wiki/wiki/Logging-into-the-Raspberry-Pi) -* [Configuring GPIO on the Raspberry Pi](https://github.com/webthingsio/wiki/wiki/Configuring-GPIO-for-use-with-the-gpio-adapter) -* [Running OAuth locally](https://github.com/WebThingsIO/wiki/wiki/Running-OAuth-Locally) -* [Command line tool for exploring new Zigbee and Z-Wave devices](https://github.com/WebThingsIO/wiki/wiki/Command-Line-Tool) -* [Installing OpenZWave](https://github.com/WebThingsIO/wiki/wiki/Installing-OpenZWave) -* [Node for OpenZWave](https://github.com/WebThingsIO/wiki/wiki/Node-for-OpenZWave) -* [Debugging Z-Wave](https://github.com/WebThingsIO/wiki/wiki/Debugging-OpenZWave) -* [Debugging Zigbee](https://github.com/WebThingsIO/wiki/wiki/Debugging-Zigbee) -* [Recording Zigbee frames sent by XCTU](https://github.com/WebThingsIO/wiki/wiki/Recording-Frames-sent-by-XCTU-(Zigbee)) -* [Zigbee attributes](https://github.com/WebThingsIO/wiki/wiki/Zigbee-Attributes) -* [Setup of eslint in PyCharm](https://github.com/WebThingsIO/wiki/wiki/PyCharm-Setup) -* [Loop mounting a Raspberry Pi image file under Linux](https://github.com/WebThingsIO/wiki/wiki/Loop-mounting-a-Raspberry-Pi-image-file-under-Linux) - -### External Resources -* [Mozilla Hacks Blog - Web of Things](https://hacks.mozilla.org/category/web-of-things/) - Original Mozilla WebThings blog -* [TwoBraids Blog](https://www.twobraids.com/search/label/programming) - Blog posts about WebThings +See the [MkDocs user guide](https://www.mkdocs.org/user-guide/) for more. \ No newline at end of file diff --git a/_config.yml b/_config.yml deleted file mode 100644 index 4a783d7..0000000 --- a/_config.yml +++ /dev/null @@ -1,20 +0,0 @@ -theme: jekyll-theme-slate -title: WebThings Documentation -description: A guide to using and developing for the WebThings IoT Platform -baseurl: /docs -show_downloads: false -encoding: UTF-8 -markdown: kramdown -kramdown: - input: GFM - hard_wrap: false - math_engine: mathjax - syntax_highlighter: rouge -future: true -jailed: false -lsi: false -safe: true -incremental: false -highlighter: rouge -gist: - noscript: false diff --git a/docs/css/style.css b/docs/css/style.css new file mode 100644 index 0000000..ec146ab --- /dev/null +++ b/docs/css/style.css @@ -0,0 +1,16 @@ +.wy-side-nav-search, .wy-nav-top { + background-color: #5d9bc7; +} + +code { + background-color: #282c34 !important; + font-size: 13px !important; +} + +pre code { + padding: 1.5em !important; +} + +.rst-content code, .rst-content pre code { + color: #fff; +} \ No newline at end of file diff --git a/docs/framework/arduino.md b/docs/framework/arduino.md new file mode 100644 index 0000000..dc6216e --- /dev/null +++ b/docs/framework/arduino.md @@ -0,0 +1,181 @@ +# webthing-arduino + +## Installation + +### Arduino IDE + +Add the `webthing` and `ArduinoJson` libraries to your project. + +### PlatformIO + +Add the `webthing-arduino` and `ArduinoJson` libraries to your project. + +## Example + +``` + + +#define LARGE_JSON_BUFFERS 1 + + #include + #include + #include + + #ifdef ESP32 + #include + #endif + + const char *ssid = "......"; + const char *password = ".........."; + + #if defined(LED_BUILTIN) + const int lampPin = LED_BUILTIN; + #else + const int lampPin = 13; // manually configure LED pin + #endif + + ThingActionObject *action_generator(DynamicJsonDocument *); + + WebThingAdapter *adapter; + + const char *lampTypes[] = {"OnOffSwitch", "Light", nullptr}; + ThingDevice lamp("urn:dev:ops:my-lamp-1234", "My Lamp", lampTypes); + + ThingProperty lampOn("on", "Whether the lamp is turned on", BOOLEAN, + "OnOffProperty"); + ThingProperty lampLevel("brightness", "The level of light from 0-100", INTEGER, + "BrightnessProperty"); + + StaticJsonDocument<256> fadeInput; + JsonObject fadeInputObj = fadeInput.to(); + ThingAction fade("fade", "Fade", "Fade the lamp to a given level", + "FadeAction", &fadeInputObj, action_generator); + ThingEvent overheated("overheated", + "The lamp has exceeded its safe operating temperature", + NUMBER, "OverheatedEvent"); + + bool lastOn = true; + + void setup(void) { + pinMode(lampPin, OUTPUT); + digitalWrite(lampPin, HIGH); + Serial.begin(115200); + Serial.println(""); + Serial.print("Connecting to \""); + Serial.print(ssid); + Serial.println("\""); + #if defined(ESP8266) || defined(ESP32) + WiFi.mode(WIFI_STA); + #endif + WiFi.begin(ssid, password); + Serial.println(""); + + // Wait for connection + while (WiFi.status() != WL_CONNECTED) { + delay(500); + Serial.print("."); + } + + Serial.println(""); + Serial.print("Connected to "); + Serial.println(ssid); + Serial.print("IP address: "); + Serial.println(WiFi.localIP()); + adapter = new WebThingAdapter("led-lamp", WiFi.localIP()); + + lamp.description = "A web connected lamp"; + + lampOn.title = "On/Off"; + lamp.addProperty(&lampOn); + + lampLevel.title = "Brightness"; + lampLevel.minimum = 0; + lampLevel.maximum = 100; + lampLevel.unit = "percent"; + lamp.addProperty(&lampLevel); + + fadeInputObj["type"] = "object"; + JsonObject fadeInputProperties = + fadeInputObj.createNestedObject("properties"); + JsonObject brightnessInput = + fadeInputProperties.createNestedObject("brightness"); + brightnessInput["type"] = "integer"; + brightnessInput["minimum"] = 0; + brightnessInput["maximum"] = 100; + brightnessInput["unit"] = "percent"; + JsonObject durationInput = + fadeInputProperties.createNestedObject("duration"); + durationInput["type"] = "integer"; + durationInput["minimum"] = 1; + durationInput["unit"] = "milliseconds"; + lamp.addAction(&fade); + + overheated.unit = "degree celsius"; + lamp.addEvent(&overheated); + + adapter->addDevice(&lamp); + adapter->begin(); + + Serial.println("HTTP server started"); + Serial.print("http://"); + Serial.print(WiFi.localIP()); + Serial.print("/things/"); + Serial.println(lamp.id); + + #ifdef analogWriteRange + analogWriteRange(255); + #endif + + // set initial values + ThingPropertyValue initialOn = {.boolean = true}; + lampOn.setValue(initialOn); + (void)lampOn.changedValueOrNull(); + + ThingPropertyValue initialLevel = {.integer = 50}; + lampLevel.setValue(initialLevel); + (void)lampLevel.changedValueOrNull(); + + analogWrite(lampPin, 128); + + randomSeed(analogRead(0)); + } + + void loop(void) { + adapter->update(); + bool on = lampOn.getValue().boolean; + if (on) { + int level = map(lampLevel.getValue().number, 0, 100, 255, 0); + analogWrite(lampPin, level); + } else { + analogWrite(lampPin, 255); + } + + if (lastOn != on) { + lastOn = on; + } + } + + void do_fade(const JsonVariant &input) { + JsonObject inputObj = input.as(); + long long int duration = inputObj["duration"]; + long long int brightness = inputObj["brightness"]; + + delay(duration); + + ThingDataValue value = {.integer = brightness}; + lampLevel.setValue(value); + int level = map(brightness, 0, 100, 255, 0); + analogWrite(lampPin, level); + + ThingDataValue val; + val.number = 102; + ThingEventObject *ev = new ThingEventObject("overheated", NUMBER, val); + lamp.queueEventObject(ev); + } + + ThingActionObject *action_generator(DynamicJsonDocument *input) { + return new ThingActionObject("fade", input, do_fade, nullptr); + } + + +``` \ No newline at end of file diff --git a/docs/framework/images/webthings_framework_banner.png b/docs/framework/images/webthings_framework_banner.png new file mode 100644 index 0000000..1e8246d Binary files /dev/null and b/docs/framework/images/webthings_framework_banner.png differ diff --git a/docs/framework/introduction.md b/docs/framework/introduction.md new file mode 100644 index 0000000..fc8f4c9 --- /dev/null +++ b/docs/framework/introduction.md @@ -0,0 +1,11 @@ +# WebThings Framework + +![An illustration of a collection of connected devices](images/webthings_framework_banner.png) + +*Build your own web things.* + +The [WebThings Framework](https://webthings.io/framework/) is a collection of re-usable software components to help developers build their own web things. + +This section contains installation instructions and examples showing how to create a web thing in a range of different programming languages. + +**🗒️ Note:** *Most of these libraries implement Mozilla's legacy [Web Thing API](https://webthings.io/api/) and have not yet been updated to conform to the latest [W3C WoT standards](https://www.w3.org/WoT/). Contributions to bring these libraries up to date are gratefully received on [GitHub](https://github.com/WebThingsIO/).* \ No newline at end of file diff --git a/docs/framework/java.md b/docs/framework/java.md new file mode 100644 index 0000000..8dd6eb6 --- /dev/null +++ b/docs/framework/java.md @@ -0,0 +1,166 @@ +# webthing-java + +## Installation + +### Maven + +``` + + + io.webthings + webthing + 0.13.0 + + +``` + +### Gradle + +``` +dependencies { + runtime( + [group: 'io.webthings', name: 'webthing', version: '0.13.0'], + ) + } +``` + +## Example + +``` + + +package io.webthings.webthing.example; + +import org.json.JSONArray; +import org.json.JSONObject; +import io.webthings.webthing.Action; +import io.webthings.webthing.Event; +import io.webthings.webthing.Property; +import io.webthings.webthing.Thing; +import io.webthings.webthing.Value; +import io.webthings.webthing.WebThingServer; +import io.webthings.webthing.errors.PropertyError; + +import java.io.IOException; +import java.util.Arrays; +import java.util.UUID; + +public class SingleThing { + public static Thing makeThing() { + Thing thing = new Thing("urn:dev:ops:my-lamp-1234", + "My Lamp", + new JSONArray(Arrays.asList("OnOffSwitch", + "Light")), + "A web connected lamp"); + + JSONObject onDescription = new JSONObject(); + onDescription.put("@type", "OnOffProperty"); + onDescription.put("title", "On/Off"); + onDescription.put("type", "boolean"); + onDescription.put("description", "Whether the lamp is turned on"); + thing.addProperty(new Property(thing, + "on", + new Value(true), + onDescription)); + + JSONObject brightnessDescription = new JSONObject(); + brightnessDescription.put("@type", "BrightnessProperty"); + brightnessDescription.put("title", "Brightness"); + brightnessDescription.put("type", "integer"); + brightnessDescription.put("description", + "The level of light from 0-100"); + brightnessDescription.put("minimum", 0); + brightnessDescription.put("maximum", 100); + brightnessDescription.put("unit", "percent"); + thing.addProperty(new Property(thing, + "brightness", + new Value(50), + brightnessDescription)); + + JSONObject fadeMetadata = new JSONObject(); + JSONObject fadeInput = new JSONObject(); + JSONObject fadeProperties = new JSONObject(); + JSONObject fadeBrightness = new JSONObject(); + JSONObject fadeDuration = new JSONObject(); + fadeMetadata.put("title", "Fade"); + fadeMetadata.put("description", "Fade the lamp to a given level"); + fadeInput.put("type", "object"); + fadeInput.put("required", + new JSONArray(Arrays.asList("brightness", "duration"))); + fadeBrightness.put("type", "integer"); + fadeBrightness.put("minimum", 0); + fadeBrightness.put("maximum", 100); + fadeBrightness.put("unit", "percent"); + fadeDuration.put("type", "integer"); + fadeDuration.put("minimum", 1); + fadeDuration.put("unit", "milliseconds"); + fadeProperties.put("brightness", fadeBrightness); + fadeProperties.put("duration", fadeDuration); + fadeInput.put("properties", fadeProperties); + fadeMetadata.put("input", fadeInput); + thing.addAvailableAction("fade", fadeMetadata, FadeAction.class); + + JSONObject overheatedMetadata = new JSONObject(); + overheatedMetadata.put("description", + "The lamp has exceeded its safe operating temperature"); + overheatedMetadata.put("type", "number"); + overheatedMetadata.put("unit", "degree celsius"); + thing.addAvailableEvent("overheated", overheatedMetadata); + + return thing; + } + + public static void main(String[] args) { + Thing thing = makeThing(); + WebThingServer server; + + try { + // If adding more than one thing, use MultipleThings() with a name. + // In the single thing case, the thing's name will be broadcast. + server = new WebThingServer(new WebThingServer.SingleThing(thing), + 8888); + + Runtime.getRuntime().addShutdownHook(new Thread() { + public void run() { + server.stop(); + } + }); + + server.start(false); + } catch (IOException e) { + System.out.println(e); + System.exit(1); + } + } + + public static class OverheatedEvent extends Event { + public OverheatedEvent(Thing thing, int data) { + super(thing, "overheated", data); + } + } + + public static class FadeAction extends Action { + public FadeAction(Thing thing, JSONObject input) { + super(UUID.randomUUID().toString(), thing, "fade", input); + } + + @Override + public void performAction() { + Thing thing = this.getThing(); + JSONObject input = this.getInput(); + try { + Thread.sleep(input.getInt("duration")); + } catch (InterruptedException e) { + } + + try { + thing.setProperty("brightness", input.getInt("brightness")); + thing.addEvent(new OverheatedEvent(thing, 102)); + } catch (PropertyError e) { + } + } + } +} + + +``` \ No newline at end of file diff --git a/docs/framework/micropython.md b/docs/framework/micropython.md new file mode 100644 index 0000000..f550439 --- /dev/null +++ b/docs/framework/micropython.md @@ -0,0 +1,3 @@ +# webthing-upy + +See [README](https://github.com/WebThingsIO/webthing-upy#readme) on GitHub. \ No newline at end of file diff --git a/docs/framework/node-js.md b/docs/framework/node-js.md new file mode 100644 index 0000000..739fc44 --- /dev/null +++ b/docs/framework/node-js.md @@ -0,0 +1,127 @@ +# webthing-node + +## Installation + +`$ npm install webthing` + +## Example + +``` +const { + Action, + Event, + Property, + SingleThing, + Thing, + Value, + WebThingServer, +} = require('webthing'); +const uuidv4 = require('uuid/v4'); + +class OverheatedEvent extends Event { + constructor(thing, data) { + super(thing, 'overheated', data); + } +} + +class FadeAction extends Action { + constructor(thing, input) { + super(uuidv4(), thing, 'fade', input); + } + + performAction() { + return new Promise((resolve) = & gt; + { + setTimeout(() = & gt; + { + this.thing.setProperty('brightness', this.input.brightness); + this.thing.addEvent(new OverheatedEvent(this.thing, 102)); + resolve(); + }, this.input.duration); + }); + } +} + +function makeThing() { + const thing = new Thing('urn:dev:ops:my-lamp-1234', + 'My Lamp', + ['OnOffSwitch', 'Light'], + 'A web connected lamp'); + + thing.addProperty( + new Property(thing, + 'on', + new Value(true), { + '@type': 'OnOffProperty', + title: 'On/Off', + type: 'boolean', + description: 'Whether the lamp is turned on', + })); + thing.addProperty( + new Property(thing, + 'brightness', + new Value(50), { + '@type': 'BrightnessProperty', + title: 'Brightness', + type: 'integer', + description: 'The level of light from 0-100', + minimum: 0, + maximum: 100, + unit: 'percent', + })); + + thing.addAvailableAction( + 'fade', { + title: 'Fade', + description: 'Fade the lamp to a given level', + input: { + type: 'object', + required: [ + 'brightness', + 'duration', + ], + properties: { + brightness: { + type: 'integer', + minimum: 0, + maximum: 100, + unit: 'percent', + }, + duration: { + type: 'integer', + minimum: 1, + unit: 'milliseconds', + }, + }, + }, + }, + FadeAction); + + thing.addAvailableEvent( + 'overheated', { + description: 'The lamp has exceeded its safe operating temperature', + type: 'number', + unit: 'degree celsius', + }); + + return thing; +} + +function runServer() { + const thing = makeThing(); + + // If adding more than one thing, use MultipleThings() with a name. + // In the single thing case, the thing's name will be broadcast. + const server = new WebThingServer(new SingleThing(thing), 8888); + + process.on('SIGINT', () = & gt; + { + server.stop().then(() = & gt; process.exit()).catch(() = & gt; process.exit()); + }); + + server.start().catch(console.error); +} + +runServer(); + +``` \ No newline at end of file diff --git a/docs/framework/python.md b/docs/framework/python.md new file mode 100644 index 0000000..99dff6a --- /dev/null +++ b/docs/framework/python.md @@ -0,0 +1,132 @@ +# webthing-python + +## Installation + +`$ pip install webthing` + +## Example + +``` + + +from __future__ import division + from webthing import (Action, Event, Property, SingleThing, Thing, Value, + WebThingServer) + import logging + import time + import uuid + + + class OverheatedEvent(Event): + + def __init__(self, thing, data): + Event.__init__(self, thing, 'overheated', data=data) + + + class FadeAction(Action): + + def __init__(self, thing, input_): + Action.__init__(self, uuid.uuid4().hex, thing, 'fade', input_=input_) + + def perform_action(self): + time.sleep(self.input['duration'] / 1000) + self.thing.set_property('brightness', self.input['brightness']) + self.thing.add_event(OverheatedEvent(self.thing, 102)) + + + def make_thing(): + thing = Thing( + 'urn:dev:ops:my-lamp-1234', + 'My Lamp', + ['OnOffSwitch', 'Light'], + 'A web connected lamp' + ) + + thing.add_property( + Property(thing, + 'on', + Value(True), + metadata={ + '@type': 'OnOffProperty', + 'title': 'On/Off', + 'type': 'boolean', + 'description': 'Whether the lamp is turned on', + })) + thing.add_property( + Property(thing, + 'brightness', + Value(50), + metadata={ + '@type': 'BrightnessProperty', + 'title': 'Brightness', + 'type': 'integer', + 'description': 'The level of light from 0-100', + 'minimum': 0, + 'maximum': 100, + 'unit': 'percent', + })) + + thing.add_available_action( + 'fade', + { + 'title': 'Fade', + 'description': 'Fade the lamp to a given level', + 'input': { + 'type': 'object', + 'required': [ + 'brightness', + 'duration', + ], + 'properties': { + 'brightness': { + 'type': 'integer', + 'minimum': 0, + 'maximum': 100, + 'unit': 'percent', + }, + 'duration': { + 'type': 'integer', + 'minimum': 1, + 'unit': 'milliseconds', + }, + }, + }, + }, + FadeAction) + + thing.add_available_event( + 'overheated', + { + 'description': + 'The lamp has exceeded its safe operating temperature', + 'type': 'number', + 'unit': 'degree celsius', + }) + + return thing + + + def run_server(): + thing = make_thing() + + # If adding more than one thing, use MultipleThings() with a name. + # In the single thing case, the thing's name will be broadcast. + server = WebThingServer(SingleThing(thing), port=8888) + try: + logging.info('starting the server') + server.start() + except KeyboardInterrupt: + logging.info('stopping the server') + server.stop() + logging.info('done') + + + if __name__ == '__main__': + logging.basicConfig( + level=10, + format="%(asctime)s %(filename)s:%(lineno)s %(levelname)s %(message)s" + ) + run_server() + + +``` \ No newline at end of file diff --git a/docs/framework/rust.md b/docs/framework/rust.md new file mode 100644 index 0000000..293b30f --- /dev/null +++ b/docs/framework/rust.md @@ -0,0 +1,248 @@ +# webthing-rust + +## Installation + +### Cargo + +``` +[dependencies] + webthing = "0.13" +``` + +## Example + +``` +use actix_rt; + use serde_json::json; + use std::sync::{Arc, RwLock, Weak}; + use std::{thread, time}; + use uuid::Uuid; + use webthing::{ + Action, BaseAction, BaseEvent, BaseProperty, BaseThing, Thing, ThingsType, WebThingServer, + }; + + use webthing::server::ActionGenerator; + + pub struct FadeAction(BaseAction); + + impl FadeAction { + fn new( + input: Option>, + thing: Weak>>, + ) -> FadeAction { + FadeAction(BaseAction::new( + Uuid::new_v4().to_string(), + "fade".to_owned(), + input, + thing, + )) + } + } + + impl Action for FadeAction { + fn set_href_prefix(&mut self, prefix: String) { + self.0.set_href_prefix(prefix) + } + + fn get_id(&self) -> String { + self.0.get_id() + } + + fn get_name(&self) -> String { + self.0.get_name() + } + + fn get_href(&self) -> String { + self.0.get_href() + } + + fn get_status(&self) -> String { + self.0.get_status() + } + + fn get_time_requested(&self) -> String { + self.0.get_time_requested() + } + + fn get_time_completed(&self) -> Option { + self.0.get_time_completed() + } + + fn get_input(&self) -> Option> { + self.0.get_input() + } + + fn get_thing(&self) -> Option>>> { + self.0.get_thing() + } + + fn set_status(&mut self, status: String) { + self.0.set_status(status) + } + + fn start(&mut self) { + self.0.start() + } + + fn perform_action(&mut self) { + let thing = self.get_thing(); + if thing.is_none() { + return; + } + + let thing = thing.unwrap(); + let input = self.get_input().unwrap().clone(); + let name = self.get_name(); + let id = self.get_id(); + + thread::spawn(move || { + thread::sleep(time::Duration::from_millis( + input.get("duration").unwrap().as_u64().unwrap(), + )); + + let thing = thing.clone(); + let mut thing = thing.write().unwrap(); + let _ = thing.set_property( + "brightness".to_owned(), + input.get("brightness").unwrap().clone(), + ); + thing.add_event(Box::new(BaseEvent::new( + "overheated".to_owned(), + Some(json!(102)), + ))); + + thing.finish_action(name, id); + }); + } + + fn cancel(&mut self) { + self.0.cancel() + } + + fn finish(&mut self) { + self.0.finish() + } + } + + struct Generator; + + impl ActionGenerator for Generator { + fn generate( + &self, + thing: Weak>>, + name: String, + input: Option<&serde_json::Value>, + ) -> Option> { + let input = match input { + Some(v) => match v.as_object() { + Some(o) => Some(o.clone()), + None => None, + }, + None => None, + }; + + let name: &str = &name; + match name { + "fade" => Some(Box::new(FadeAction::new(input, thing))), + _ => None, + } + } + } + + fn make_thing() -> Arc>> { + let mut thing = BaseThing::new( + "urn:dev:ops:my-lamp-1234".to_owned(), + "My Lamp".to_owned(), + Some(vec!["OnOffSwitch".to_owned(), "Light".to_owned()]), + Some("A web connected lamp".to_owned()), + ); + + let on_description = json!({ + "@type": "OnOffProperty", + "title": "On/Off", + "type": "boolean", + "description": "Whether the lamp is turned on" + }); + let on_description = on_description.as_object().unwrap().clone(); + thing.add_property(Box::new(BaseProperty::new( + "on".to_owned(), + json!(true), + None, + Some(on_description), + ))); + + let brightness_description = json!({ + "@type": "BrightnessProperty", + "title": "Brightness", + "type": "integer", + "description": "The level of light from 0-100", + "minimum": 0, + "maximum": 100, + "unit": "percent" + }); + let brightness_description = brightness_description.as_object().unwrap().clone(); + thing.add_property(Box::new(BaseProperty::new( + "brightness".to_owned(), + json!(50), + None, + Some(brightness_description), + ))); + + let fade_metadata = json!({ + "title": "Fade", + "description": "Fade the lamp to a given level", + "input": { + "type": "object", + "required": [ + "brightness", + "duration" + ], + "properties": { + "brightness": { + "type": "integer", + "minimum": 0, + "maximum": 100, + "unit": "percent" + }, + "duration": { + "type": "integer", + "minimum": 1, + "unit": "milliseconds" + } + } + } + }); + let fade_metadata = fade_metadata.as_object().unwrap().clone(); + thing.add_available_action("fade".to_owned(), fade_metadata); + + let overheated_metadata = json!({ + "description": "The lamp has exceeded its safe operating temperature", + "type": "number", + "unit": "degree celsius" + }); + let overheated_metadata = overheated_metadata.as_object().unwrap().clone(); + thing.add_available_event("overheated".to_owned(), overheated_metadata); + + Arc::new(RwLock::new(Box::new(thing))) + } + + #[actix_rt::main] + async fn main() -> std::io::Result<()> { + env_logger::init(); + let thing = make_thing(); + + // If adding more than one thing, use ThingsType::Multiple() with a name. + // In the single thing case, the thing's name will be broadcast. + let mut server = WebThingServer::new( + ThingsType::Single(thing), + Some(8888), + None, + None, + Box::new(Generator), + None, + ); + server.start(None).await + } + + +``` \ No newline at end of file diff --git a/docs/gateway/floorplan.md b/docs/gateway/floorplan.md new file mode 100644 index 0000000..86dfaaa --- /dev/null +++ b/docs/gateway/floorplan.md @@ -0,0 +1,52 @@ +# Floorplan + +The floorplan view enables you to lay out your things on an interactive floorplan of your home. + +To navigate to the floorplan view, select the "Floorplan" option in the main menu. + +![Screenshot of the main menu with the "Floorplan" option selected](images/main_menu-floorplan.png) + +## Upload Floorplan + +The first time you view the floorplan view you will see all your things un-arranged in a row at the top of the screen. + +![Screenshot of the floorplan view without a floorplan uploaded](images/floorplan-missing.png) + +To upload a floorplan of your home, first click on the "✎" button at the bottom right of the screen to enter the edit floorplan view. + +![Screenshot of the edit floorplan view without a floorplan uploaded](images/floorplan-edit-unarranged.png) + +From the edit floorplan view, click the "Upload floorplan..." button to upload a floorplan image of your home. + +**💡 Tip:** You can upload any image file that can be rendered by web browsers including scanned images or even a photograph. For best results we recommend an SVG file with white lines and a transparent background. + +Once you have uploaded your image, click the "✔" button at the bottom right of the screen to exit the edit view. + +![Screenshot of the floorplan view with a floorplan uploaded by things still unarranged](images/floorplan-uploaded-unarranged.png) + +## Re-arrange Things + +To arrange your things on the floorplan, first click the "✎" button at the bottom right of the screen. + +You can then drag and drop the things into position on the floorplan. + +![Screenshot of the edit floorplan view with things arranged on an uploaded floorplan](images/floorplan-edit-arranged.png) + +Once you have finished re-arranging things, click the "✔" button at the bottom right of the screen to exit the edit view. + +![Screenshot of the floorplan view with things arranged on an uploaded floorplan](images/floorplan_view.png) + +## Monitor & Control Things + +The thing icons in the floorplan view show a live overview of their current state. + +You can toggle things on and off from the floorplan view by clicking them. + +![Screenshot of the floorplan view with some things switched on](images/floorplan_view-lights_on.png) + +To navigate to the detail view for a particular thing, long press its thing icon. + +![Screenshot of the detail view of a thing](images/thing_detail-colored_light.png) + + + diff --git a/docs/gateway/hacking.md b/docs/gateway/hacking.md new file mode 100644 index 0000000..ec86c64 --- /dev/null +++ b/docs/gateway/hacking.md @@ -0,0 +1,27 @@ +# Development + +WebThings Gateway is an open source project maintained by a community of volunteers. + +To get started hacking on the gateway, see the [README](https://github.com/WebThingsIO/gateway/blob/master/README.md) and [wiki](https://github.com/WebThingsIO/wiki/wiki/). + +The API exposed by the gateway is called the [Web Thing API](https://webthings.io/api/). We are currently in the process of migrating this API to conform with [W3C Web of Things](../../wot/introduction) standards. You can see an overview of differences between the two [here](https://github.com/webthingsio/wiki/wiki/Mozilla-W3C-Differences). + +## Add-on Development + +WebThings Gateway has a directory of community-contributed [add-ons](../settings#add-ons) which enhance its capabilities. + +To learn how to develop your own add-on or contribute to an existing one, you may want to start with the resources below: + +* [Introduction to Add-ons](https://github.com/WebThingsIO/addon-list/blob/master/guidelines.md) +* [Creating an Add-on](https://github.com/WebThingsIO/wiki/wiki/HOWTO%3A-Create-an-add-on) +* [Configuring an Add-on](https://github.com/WebThingsIO/wiki/wiki/Add-on-Configuration) +* [Publishing an Add-on](https://github.com/WebThingsIO/addon-list#readme) +* Examples: + * [Adapter Add-on](https://github.com/WebThingsIO/example-adapter) + * [Notifier Add-on](https://github.com/WebThingsIO/example-notifier) + * [Extension Add-on](https://github.com/WebThingsIO/example-extension) +* Add-on APIs + * [Node.js Add-on API](https://github.com/WebThingsIO/gateway-addon-node) + * [Python Add-on API](https://github.com/WebThingsIO/gateway-addon-python) +* [Adapter Inter-process communication](https://github.com/WebThingsIO/wiki/wiki/Adapter-IPC) +* [Debug Controller](https://github.com/WebThingsIO/wiki/wiki/Using-the-debug-controller) \ No newline at end of file diff --git a/docs/gateway/images/action_and_events_things.png b/docs/gateway/images/action_and_events_things.png new file mode 100644 index 0000000..b0333c9 Binary files /dev/null and b/docs/gateway/images/action_and_events_things.png differ diff --git a/docs/gateway/images/action_input.png b/docs/gateway/images/action_input.png new file mode 100644 index 0000000..2494675 Binary files /dev/null and b/docs/gateway/images/action_input.png differ diff --git a/docs/gateway/images/add-ons_screen.png b/docs/gateway/images/add-ons_screen.png new file mode 100644 index 0000000..321a4fa Binary files /dev/null and b/docs/gateway/images/add-ons_screen.png differ diff --git a/docs/gateway/images/add_add-on.png b/docs/gateway/images/add_add-on.png new file mode 100644 index 0000000..1847d6f Binary files /dev/null and b/docs/gateway/images/add_add-on.png differ diff --git a/docs/gateway/images/add_thing_by_url.png b/docs/gateway/images/add_thing_by_url.png new file mode 100644 index 0000000..0c467a4 Binary files /dev/null and b/docs/gateway/images/add_thing_by_url.png differ diff --git a/docs/gateway/images/add_thing_screen-new_things.png b/docs/gateway/images/add_thing_screen-new_things.png new file mode 100644 index 0000000..300e548 Binary files /dev/null and b/docs/gateway/images/add_thing_screen-new_things.png differ diff --git a/docs/gateway/images/add_thing_screen-scanning.png b/docs/gateway/images/add_thing_screen-scanning.png new file mode 100644 index 0000000..36ba077 Binary files /dev/null and b/docs/gateway/images/add_thing_screen-scanning.png differ diff --git a/docs/gateway/images/add_user.png b/docs/gateway/images/add_user.png new file mode 100644 index 0000000..77336c1 Binary files /dev/null and b/docs/gateway/images/add_user.png differ diff --git a/docs/gateway/images/assembly.png b/docs/gateway/images/assembly.png new file mode 100644 index 0000000..4522b25 Binary files /dev/null and b/docs/gateway/images/assembly.png differ diff --git a/docs/gateway/images/authorisation_request.png b/docs/gateway/images/authorisation_request.png new file mode 100644 index 0000000..3087dda Binary files /dev/null and b/docs/gateway/images/authorisation_request.png differ diff --git a/docs/gateway/images/authorisations.png b/docs/gateway/images/authorisations.png new file mode 100644 index 0000000..6be65a2 Binary files /dev/null and b/docs/gateway/images/authorisations.png differ diff --git a/docs/gateway/images/choose_subdomain.png b/docs/gateway/images/choose_subdomain.png new file mode 100644 index 0000000..4a9e617 Binary files /dev/null and b/docs/gateway/images/choose_subdomain.png differ diff --git a/docs/gateway/images/components.png b/docs/gateway/images/components.png new file mode 100644 index 0000000..5346bfa Binary files /dev/null and b/docs/gateway/images/components.png differ diff --git a/docs/gateway/images/confirm_remove_thing.png b/docs/gateway/images/confirm_remove_thing.png new file mode 100644 index 0000000..6018fe3 Binary files /dev/null and b/docs/gateway/images/confirm_remove_thing.png differ diff --git a/docs/gateway/images/connect_wifi.png b/docs/gateway/images/connect_wifi.png new file mode 100644 index 0000000..64b36c9 Binary files /dev/null and b/docs/gateway/images/connect_wifi.png differ diff --git a/docs/gateway/images/create_user.png b/docs/gateway/images/create_user.png new file mode 100644 index 0000000..2a75f74 Binary files /dev/null and b/docs/gateway/images/create_user.png differ diff --git a/docs/gateway/images/developer_settings.png b/docs/gateway/images/developer_settings.png new file mode 100644 index 0000000..643758c Binary files /dev/null and b/docs/gateway/images/developer_settings.png differ diff --git a/docs/gateway/images/domain_settings.png b/docs/gateway/images/domain_settings.png new file mode 100644 index 0000000..414eb64 Binary files /dev/null and b/docs/gateway/images/domain_settings.png differ diff --git a/docs/gateway/images/edit_rule_button.png b/docs/gateway/images/edit_rule_button.png new file mode 100644 index 0000000..6d58a07 Binary files /dev/null and b/docs/gateway/images/edit_rule_button.png differ diff --git a/docs/gateway/images/edit_thing.png b/docs/gateway/images/edit_thing.png new file mode 100644 index 0000000..7d35b4a Binary files /dev/null and b/docs/gateway/images/edit_thing.png differ diff --git a/docs/gateway/images/edit_thing_option.png b/docs/gateway/images/edit_thing_option.png new file mode 100644 index 0000000..4e55477 Binary files /dev/null and b/docs/gateway/images/edit_thing_option.png differ diff --git a/docs/gateway/images/edit_user-two-factor_auth1.png b/docs/gateway/images/edit_user-two-factor_auth1.png new file mode 100644 index 0000000..4e9ba29 Binary files /dev/null and b/docs/gateway/images/edit_user-two-factor_auth1.png differ diff --git a/docs/gateway/images/edit_user-two-factor_auth2.png b/docs/gateway/images/edit_user-two-factor_auth2.png new file mode 100644 index 0000000..24564d9 Binary files /dev/null and b/docs/gateway/images/edit_user-two-factor_auth2.png differ diff --git a/docs/gateway/images/edit_user-two_factor_auth0.png b/docs/gateway/images/edit_user-two_factor_auth0.png new file mode 100644 index 0000000..1b49437 Binary files /dev/null and b/docs/gateway/images/edit_user-two_factor_auth0.png differ diff --git a/docs/gateway/images/edit_user.png b/docs/gateway/images/edit_user.png new file mode 100644 index 0000000..c1f90c9 Binary files /dev/null and b/docs/gateway/images/edit_user.png differ diff --git a/docs/gateway/images/empty_things_screen.png b/docs/gateway/images/empty_things_screen.png new file mode 100644 index 0000000..591b608 Binary files /dev/null and b/docs/gateway/images/empty_things_screen.png differ diff --git a/images/etcher_screenshot.png b/docs/gateway/images/etcher_screenshot.png similarity index 100% rename from images/etcher_screenshot.png rename to docs/gateway/images/etcher_screenshot.png diff --git a/docs/gateway/images/event_log.png b/docs/gateway/images/event_log.png new file mode 100644 index 0000000..80cf590 Binary files /dev/null and b/docs/gateway/images/event_log.png differ diff --git a/docs/gateway/images/event_log_option.png b/docs/gateway/images/event_log_option.png new file mode 100644 index 0000000..426580e Binary files /dev/null and b/docs/gateway/images/event_log_option.png differ diff --git a/docs/gateway/images/experiments.png b/docs/gateway/images/experiments.png new file mode 100644 index 0000000..02fa3a3 Binary files /dev/null and b/docs/gateway/images/experiments.png differ diff --git a/docs/gateway/images/floorplan-edit-arranged.png b/docs/gateway/images/floorplan-edit-arranged.png new file mode 100644 index 0000000..33da3cc Binary files /dev/null and b/docs/gateway/images/floorplan-edit-arranged.png differ diff --git a/docs/gateway/images/floorplan-edit-unarranged.png b/docs/gateway/images/floorplan-edit-unarranged.png new file mode 100644 index 0000000..3e4ba83 Binary files /dev/null and b/docs/gateway/images/floorplan-edit-unarranged.png differ diff --git a/docs/gateway/images/floorplan-missing.png b/docs/gateway/images/floorplan-missing.png new file mode 100644 index 0000000..79b78af Binary files /dev/null and b/docs/gateway/images/floorplan-missing.png differ diff --git a/docs/gateway/images/floorplan-uploaded-unarranged.png b/docs/gateway/images/floorplan-uploaded-unarranged.png new file mode 100644 index 0000000..309eefb Binary files /dev/null and b/docs/gateway/images/floorplan-uploaded-unarranged.png differ diff --git a/docs/gateway/images/floorplan_view-lights_on.png b/docs/gateway/images/floorplan_view-lights_on.png new file mode 100644 index 0000000..bf1b3de Binary files /dev/null and b/docs/gateway/images/floorplan_view-lights_on.png differ diff --git a/docs/gateway/images/floorplan_view.png b/docs/gateway/images/floorplan_view.png new file mode 100644 index 0000000..d4111ae Binary files /dev/null and b/docs/gateway/images/floorplan_view.png differ diff --git a/docs/gateway/images/localisation_settings.png b/docs/gateway/images/localisation_settings.png new file mode 100644 index 0000000..268e1ea Binary files /dev/null and b/docs/gateway/images/localisation_settings.png differ diff --git a/docs/gateway/images/log_in.png b/docs/gateway/images/log_in.png new file mode 100644 index 0000000..eae00e7 Binary files /dev/null and b/docs/gateway/images/log_in.png differ diff --git a/docs/gateway/images/log_out.png b/docs/gateway/images/log_out.png new file mode 100644 index 0000000..e049b0f Binary files /dev/null and b/docs/gateway/images/log_out.png differ diff --git a/docs/gateway/images/logs_screen-empty.png b/docs/gateway/images/logs_screen-empty.png new file mode 100644 index 0000000..c3979ce Binary files /dev/null and b/docs/gateway/images/logs_screen-empty.png differ diff --git a/docs/gateway/images/main_menu-floorplan.png b/docs/gateway/images/main_menu-floorplan.png new file mode 100644 index 0000000..310af77 Binary files /dev/null and b/docs/gateway/images/main_menu-floorplan.png differ diff --git a/docs/gateway/images/main_menu-logs.png b/docs/gateway/images/main_menu-logs.png new file mode 100644 index 0000000..15e1797 Binary files /dev/null and b/docs/gateway/images/main_menu-logs.png differ diff --git a/docs/gateway/images/main_menu-rules-selected.png b/docs/gateway/images/main_menu-rules-selected.png new file mode 100644 index 0000000..319f789 Binary files /dev/null and b/docs/gateway/images/main_menu-rules-selected.png differ diff --git a/docs/gateway/images/main_menu-settings.png b/docs/gateway/images/main_menu-settings.png new file mode 100644 index 0000000..a026331 Binary files /dev/null and b/docs/gateway/images/main_menu-settings.png differ diff --git a/docs/gateway/images/network_settings-ethernet-automatic.png b/docs/gateway/images/network_settings-ethernet-automatic.png new file mode 100644 index 0000000..a72dc5a Binary files /dev/null and b/docs/gateway/images/network_settings-ethernet-automatic.png differ diff --git a/docs/gateway/images/network_settings-ethernet-manual.png b/docs/gateway/images/network_settings-ethernet-manual.png new file mode 100644 index 0000000..4dbc08e Binary files /dev/null and b/docs/gateway/images/network_settings-ethernet-manual.png differ diff --git a/docs/gateway/images/network_settings-wifi.png b/docs/gateway/images/network_settings-wifi.png new file mode 100644 index 0000000..9008d47 Binary files /dev/null and b/docs/gateway/images/network_settings-wifi.png differ diff --git a/docs/gateway/images/network_settings-wifi_password.png b/docs/gateway/images/network_settings-wifi_password.png new file mode 100644 index 0000000..fe71566 Binary files /dev/null and b/docs/gateway/images/network_settings-wifi_password.png differ diff --git a/docs/gateway/images/network_settings.png b/docs/gateway/images/network_settings.png new file mode 100644 index 0000000..9bba9b8 Binary files /dev/null and b/docs/gateway/images/network_settings.png differ diff --git a/docs/gateway/images/new_log.png b/docs/gateway/images/new_log.png new file mode 100644 index 0000000..e194044 Binary files /dev/null and b/docs/gateway/images/new_log.png differ diff --git a/docs/gateway/images/new_rule-and.png b/docs/gateway/images/new_rule-and.png new file mode 100644 index 0000000..95711de Binary files /dev/null and b/docs/gateway/images/new_rule-and.png differ diff --git a/docs/gateway/images/new_rule-choose-input.png b/docs/gateway/images/new_rule-choose-input.png new file mode 100644 index 0000000..b1aa0b1 Binary files /dev/null and b/docs/gateway/images/new_rule-choose-input.png differ diff --git a/docs/gateway/images/new_rule-choose_output.png b/docs/gateway/images/new_rule-choose_output.png new file mode 100644 index 0000000..5cb10ed Binary files /dev/null and b/docs/gateway/images/new_rule-choose_output.png differ diff --git a/docs/gateway/images/new_rule-complete.png b/docs/gateway/images/new_rule-complete.png new file mode 100644 index 0000000..03620ab Binary files /dev/null and b/docs/gateway/images/new_rule-complete.png differ diff --git a/docs/gateway/images/new_rule-dragging-input.png b/docs/gateway/images/new_rule-dragging-input.png new file mode 100644 index 0000000..b4f2151 Binary files /dev/null and b/docs/gateway/images/new_rule-dragging-input.png differ diff --git a/docs/gateway/images/new_rule-dragging_output.png b/docs/gateway/images/new_rule-dragging_output.png new file mode 100644 index 0000000..765947c Binary files /dev/null and b/docs/gateway/images/new_rule-dragging_output.png differ diff --git a/docs/gateway/images/new_rule-or.png b/docs/gateway/images/new_rule-or.png new file mode 100644 index 0000000..0a774cc Binary files /dev/null and b/docs/gateway/images/new_rule-or.png differ diff --git a/docs/gateway/images/new_rule-while.png b/docs/gateway/images/new_rule-while.png new file mode 100644 index 0000000..6e2bcfe Binary files /dev/null and b/docs/gateway/images/new_rule-while.png differ diff --git a/docs/gateway/images/new_rule.png b/docs/gateway/images/new_rule.png new file mode 100644 index 0000000..93bb449 Binary files /dev/null and b/docs/gateway/images/new_rule.png differ diff --git a/docs/gateway/images/remove_log-confirm.png b/docs/gateway/images/remove_log-confirm.png new file mode 100644 index 0000000..4171574 Binary files /dev/null and b/docs/gateway/images/remove_log-confirm.png differ diff --git a/docs/gateway/images/remove_log_option.png b/docs/gateway/images/remove_log_option.png new file mode 100644 index 0000000..1d5f1be Binary files /dev/null and b/docs/gateway/images/remove_log_option.png differ diff --git a/docs/gateway/images/remove_rule-confirm.png b/docs/gateway/images/remove_rule-confirm.png new file mode 100644 index 0000000..cfb76d1 Binary files /dev/null and b/docs/gateway/images/remove_rule-confirm.png differ diff --git a/docs/gateway/images/remove_thing_option.png b/docs/gateway/images/remove_thing_option.png new file mode 100644 index 0000000..9a56774 Binary files /dev/null and b/docs/gateway/images/remove_thing_option.png differ diff --git a/docs/gateway/images/rules_screen-empty.png b/docs/gateway/images/rules_screen-empty.png new file mode 100644 index 0000000..5af802f Binary files /dev/null and b/docs/gateway/images/rules_screen-empty.png differ diff --git a/docs/gateway/images/rules_screen-invalid_rule.png b/docs/gateway/images/rules_screen-invalid_rule.png new file mode 100644 index 0000000..8e1cbf3 Binary files /dev/null and b/docs/gateway/images/rules_screen-invalid_rule.png differ diff --git a/docs/gateway/images/rules_screen-multiple_rules.png b/docs/gateway/images/rules_screen-multiple_rules.png new file mode 100644 index 0000000..5c146a9 Binary files /dev/null and b/docs/gateway/images/rules_screen-multiple_rules.png differ diff --git a/docs/gateway/images/rules_screen-single_rule.png b/docs/gateway/images/rules_screen-single_rule.png new file mode 100644 index 0000000..ae64225 Binary files /dev/null and b/docs/gateway/images/rules_screen-single_rule.png differ diff --git a/docs/gateway/images/settings_view.png b/docs/gateway/images/settings_view.png new file mode 100644 index 0000000..a7b5dcd Binary files /dev/null and b/docs/gateway/images/settings_view.png differ diff --git a/docs/gateway/images/thing_detail-colored_light.png b/docs/gateway/images/thing_detail-colored_light.png new file mode 100644 index 0000000..058e1e2 Binary files /dev/null and b/docs/gateway/images/thing_detail-colored_light.png differ diff --git a/docs/gateway/images/thing_detail-dimmable_color_light.png b/docs/gateway/images/thing_detail-dimmable_color_light.png new file mode 100644 index 0000000..5ee0ad8 Binary files /dev/null and b/docs/gateway/images/thing_detail-dimmable_color_light.png differ diff --git a/docs/gateway/images/thing_detail.png b/docs/gateway/images/thing_detail.png new file mode 100644 index 0000000..334e8d5 Binary files /dev/null and b/docs/gateway/images/thing_detail.png differ diff --git a/docs/gateway/images/things_screen-single_thing.png b/docs/gateway/images/things_screen-single_thing.png new file mode 100644 index 0000000..fc531ac Binary files /dev/null and b/docs/gateway/images/things_screen-single_thing.png differ diff --git a/docs/gateway/images/things_screen.png b/docs/gateway/images/things_screen.png new file mode 100644 index 0000000..e93a405 Binary files /dev/null and b/docs/gateway/images/things_screen.png differ diff --git a/docs/gateway/images/updates_screen.png b/docs/gateway/images/updates_screen.png new file mode 100644 index 0000000..c608d1d Binary files /dev/null and b/docs/gateway/images/updates_screen.png differ diff --git a/docs/gateway/images/users_screen.png b/docs/gateway/images/users_screen.png new file mode 100644 index 0000000..a30c04b Binary files /dev/null and b/docs/gateway/images/users_screen.png differ diff --git a/docs/gateway/images/view_log-boolean.png b/docs/gateway/images/view_log-boolean.png new file mode 100644 index 0000000..487bbec Binary files /dev/null and b/docs/gateway/images/view_log-boolean.png differ diff --git a/docs/gateway/images/view_log-populated.png b/docs/gateway/images/view_log-populated.png new file mode 100644 index 0000000..4c5e85d Binary files /dev/null and b/docs/gateway/images/view_log-populated.png differ diff --git a/docs/gateway/images/view_logs-multiple_logs.png b/docs/gateway/images/view_logs-multiple_logs.png new file mode 100644 index 0000000..7f0a50e Binary files /dev/null and b/docs/gateway/images/view_logs-multiple_logs.png differ diff --git a/docs/gateway/images/view_logs.png b/docs/gateway/images/view_logs.png new file mode 100644 index 0000000..4f49e0f Binary files /dev/null and b/docs/gateway/images/view_logs.png differ diff --git a/docs/gateway/images/view_users-multiple.png b/docs/gateway/images/view_users-multiple.png new file mode 100644 index 0000000..0e84f92 Binary files /dev/null and b/docs/gateway/images/view_users-multiple.png differ diff --git a/images/wifi_ssid.png b/docs/gateway/images/wifi_ssid.png similarity index 100% rename from images/wifi_ssid.png rename to docs/gateway/images/wifi_ssid.png diff --git a/docs/gateway/installation.md b/docs/gateway/installation.md new file mode 100644 index 0000000..6167d6a --- /dev/null +++ b/docs/gateway/installation.md @@ -0,0 +1,50 @@ +# Installation + +The recommended ways to install WebThings Gateway are to either use a pre-built OS image for a [Raspberry Pi](#raspberry-pi), or install the [Docker](#docker) image. Alternatively you can [build it from the source code](https://github.com/WebThingsIO/gateway/blob/master/README.md#prerequisites-for-building) yourself. + +## Raspberry Pi + +![Illustration of a Raspberry Pi single board computer, a microSD card and a USB dongle](images/components.png) + +To install WebThings Gateway on a Raspberry Pi you will need: + +1. A **[Raspberry Pi®](https://www.raspberrypi.com/products/)** single board computer (Raspberry Pi 3 or 4 recommended, Pi 5 not yet supported) and power supply +2. A **microSD card** (At least 8GB, class 10 recommended) +3. **USB dongles** (Optional, see the list of [supported hardware](../supported-hardware)) + +**🗒️ Note:** The Raspberry Pi 3 and 4 come with Wi-Fi and Bluetooth radios. The USB dongles are needed if you want to support other smart home protocols like Zigbee and Z-Wave. + +### 1. Download Image + +First download the latest gateway image from the [WebThings website](https://webthings.io/gateway/). + +### 2. Flash Image + +Next you will need to flash the downloaded image onto your microSD card. There are [various methods](https://www.raspberrypi.com/documentation/computers/getting-started.html) of doing this but we recommend using [Etcher](https://etcher.balena.io/). + +![Screenshot of the Etcher user interface showing an .img file as the source and a card reader as the target](images/etcher_screenshot.png) + +1. Open Etcher +2. Insert your SD card into an SD card reader attached to your computer +3. Select the downloaded image as the source file +4. Select your SD card as the target +5. Click "Flash!" + +Once flashing is complete, remove the microSD card. + +### 3. Boot Raspberry Pi + +![An illustration showing first inserting the microSD card, then inserting a USB dongle then plugging in the power supply](images/assembly.png) + + +1. Insert the flashed microSD card into your Raspberry Pi +2. Plug in any USB dongles +3. Connect the power supply to boot the Pi +4. Check that the LEDs light up: red indicates power, green indicates activity +5. Wait a few minutes for the software to boot + +**🗒️ Note:** On first boot the Raspberry Pi may take an additional 2-3 minutes longer to boot in order to take care of some first time setup. + +## Docker + +To install WebThings Gateway on Docker, follow the [instructions on Docker Hub](https://hub.docker.com/r/webthingsio/gateway). \ No newline at end of file diff --git a/docs/gateway/introduction.md b/docs/gateway/introduction.md new file mode 100644 index 0000000..d335649 --- /dev/null +++ b/docs/gateway/introduction.md @@ -0,0 +1,17 @@ +# WebThings Gateway + +*Host your own private smart home.* + +[WebThings Gateway](https://webthings.io/gateway/) is a software distribution for smart home hubs focused on privacy, security and interoperability. It enables you to securely monitor and control your home over the web, without a middleman. + +![Screenshot of the WebThings Gateway web interface, showing devices laid out on a floorplan of a home](images/floorplan_view.png) + +Features include: + + - Monitor and control all of your smart home [devices](../things) from a unified web interface + - Create "if this then that" style [rules](../rules) to automate your home with a simple drag and drop interface + - [Log](../logs) and visualise sensor data over time + - Lay out all your devices on an interactive [floorplan](../floorplan) of your home for at-a-glance status and control + - Add compatibility with more devices and protocols with adapter [add-ons](../settings#add-ons). + +The gateway bridges a range of different smart home protocols to a standardised [Web of Things](../../wot/introduction) API. \ No newline at end of file diff --git a/docs/gateway/log-in.md b/docs/gateway/log-in.md new file mode 100644 index 0000000..edc593f --- /dev/null +++ b/docs/gateway/log-in.md @@ -0,0 +1,5 @@ +# Log In + +To log into the gateway from a new device, navigate to "http://gateway.local" (whilst connected to the same local network), or your unique subdomain (e.g. "https://foo.webthings.io"), and enter your email address and password. + +![Screenshot of the login form with email and password text fields and a log in button](images/log_in.png) \ No newline at end of file diff --git a/docs/gateway/log-out.md b/docs/gateway/log-out.md new file mode 100644 index 0000000..4e078e0 --- /dev/null +++ b/docs/gateway/log-out.md @@ -0,0 +1,5 @@ +# Log Out + +To log out of your user account on the gateway, choose the "Log out" option from the main menu. + +![Screenshot of the main menu with the log out option selected](images/log_out.png) \ No newline at end of file diff --git a/docs/gateway/logs.md b/docs/gateway/logs.md new file mode 100644 index 0000000..172d366 --- /dev/null +++ b/docs/gateway/logs.md @@ -0,0 +1,60 @@ +# Logs + +The logging screen can be used to log values of properties over time and visualise that information on a graph. + +To navigate to the logs screen, choose the "Logs" option from the main menu. + +![Screenshot of the main menu with the "Logs" option selected](images/main_menu-logs.png) + +## Add Log + +To add a log, click the "+" button at the bottom right of the screen. + +![Screenshot of the empty logs screen](images/logs_screen-empty.png) + +You will then see the new log screen. + +1. Choose a device whose property you would like to log +2. Choose a numerical or boolean property you would like to log +3. Choose how long you would like to retain logged data for before it is automatically deleted +4. Click the "Save" button + +![Screenshot of the new log screen with dropdowns for device and property name, and a number field and unit dropdown for the retention period](images/new_log.png) + +You will then be navigated to the view logs screen, with an empty graph representing the log you just created. + +![Screenshot of the logs screen with one graph representing the log that was created](images/view_logs.png) + +**⚠️ Warning:** If saving logs to an SD card (e.g. on a Raspberry Pi), writing large quantities of data can shorten the life of your memory card. + +## View Logs + +To view an individual log full screen, click its title from the view logs screen. + +![Screenshot of a collection of graphs representing logs](images/view_logs-multiple_logs.png) + +The data in the log is represented as a line graph. You can set the timescale of the graph to "minute", "hour", "day" or "week" depending on the duration you'd like to view at any one time. You can then scroll through the logged data using the scrollbar at the bottom. + +![Screenshot of a line graph of a numerical property over time](images/view_log-populated.png) + +Both numerical and boolean (true/false) types of property can be logged. + +The x axis will show the timescale, and the y axis will show the range and unit of the values. + +Logs are updated in real time, which you will notice when viewing the "Minute" time resolution because the graph will animate across the screen. + +![Screenshot of a line graph of a boolean property over time](images/view_log-boolean.png) + +**💡 Tip:** You can hover over a data point to view its exact timestamp and value. + +## Remove Log + +To remove a log, from the view log screen click the overflow menu at the bottom right of the screen and click the "Remove" option. + +![Screenshot of the log overflow menu with the "Remove" option selected](images/remove_log_option.png) + +You will then be shown a confirmation dialog which will confirm that you want to permanently delete the log. + +**⚠️ Warning:** Removing a log will also permanently delete all of its data. + +![Screenshot of the remove log confirmation dialog](images/remove_log-confirm.png) diff --git a/docs/gateway/rules.md b/docs/gateway/rules.md new file mode 100644 index 0000000..aecea4f --- /dev/null +++ b/docs/gateway/rules.md @@ -0,0 +1,110 @@ +# Rules + +The rules screen provides a drag and drop graphical user interface to create "if this then that" style rules to automate your home. + +For example, if you want a light to turn on when motion is detected in a room, or sound an alarm when a door is opened. + +To navigate to the rules screen, select the Rules option from the main menu. + +![Screenshot of the main menu with the Rules option selected](images/main_menu-rules-selected.png) + +## Add Rule + +To create a rule, click the "+" button at the bottom right hand corner of the screen. + +![Screenshot of the empty rules screen](images/rules_screen-empty.png) + +You will then see the new rule screen where you can choose one or more inputs, one or more outputs and give the rule a name. + +Properties and events of devices can be used as inputs, and properties and actions can be used as outputs. + +![Screenshot of unpopulated new rule screen](images/new_rule.png) + +### Input and Output + +First, drag and drop a device from the collection of devices at the bottom to the left hand side of the rule area to choose the input device for the rule. + +![Screenshot showing the input device being dragged into place](images/new_rule-dragging-input.png) + +Next, drag and drop a device from the collection of devices at the bottom to the right hand side of the rule area to choose the output device for the rule. + +![Screenshot showing the output device being dragged into place](images/new_rule-dragging_output.png) + +Next, choose the input property or event which will trigger the rule. + +**💡 Tip:** As well as device properties and events, you can also use time as an input to trigger a rule at a particular time of day. To do this, drag and drop the the built-in "Clock" device as an input. + +**🗒️ Note:** For numerical properties you can choose a threshold above or below which the rule is triggered. + +![Screenshot showing the a dropdown menu to choose a property value or event to use as a trigger](images/new_rule-choose-input.png) + +Next, choose the output property value or action to use as an output. + +**🗒️ Note:** For numerical properties you can specify the precise value to set the property to when the rule is triggered. + +![Screenshot showing the a dropdown menu to choose a property or action to use as the output](images/new_rule-choose_output.png) + +Finally, provide a name for the rule by clicking on "Rule Name" at the top of the screen and editing the name. + +![Screenshot showing the a dropdown menu to choose a property or action to use as the output](images/new_rule-complete.png) + +You will now see the completed rule, with a line linking the input and output as well as a textual description of the rule. + +Click the back button at the top right of the screen to go back to the rules screen and you'll see your new rule has been created. + +![Screenshot showing one rule added to the rules screen](images/rules_screen-single_rule.png) + + +### If/While + +By default, rules use an "if" conditional which is triggered when a property transitions to a given value or an event is emitted. There is also a subtly different "while" conditional. + +If you want an output condition to continue until an input condition stops being true, but then revert back to its previous state (e.g. for a light to remain illuminated whilst a button is pressed), then you can instead choose the "while" option in the textual description of the rule. + +![Screenshot of a while conditional in use](images/new_rule-while.png) + +### And/Or + +When selecting multiple inputs for a rule, you can choose whether all conditions need to be true for the rule to be triggered, or just one of them. + +To only trigger the rule if all of the input conditions are true, select the "and" option in the textual description of the rule. + +![Screenshot showing the an and conditional in use](images/new_rule-and.png) + +To trigger the rule if any of the input conditions are true, select the "or" option in the textual description of the rule. + +![Screenshot showing an or conditional in use](images/new_rule-or.png) + +## View Rules + +To view all of your rules, select the "Rules" option from the main menu. + +![Screenshot showing an or conditional in use](images/rules_screen-multiple_rules.png) + +Each rule is represented by a card which shows the name and description of the rule and icons illustrating the inputs and outputs it uses. + +A rule can be toggled on and off using the on/off button. This can be useful for temporarily enabling or disabling a rule (e.g. to arm or disarm an alarm system). + +**🗒️ Note:** If a rule is missing a valid input or output, or one of the devices used as an input or output has been removed from the gateway, the rule may show as "invalid". + +![Screenshot showing invalid rule](images/rules_screen-invalid_rule.png) + +## Edit Rule + +To edit a rule, hover over its card in the rules view and click the "Edit Rule" button. + +![Screenshot showing an or conditional in use](images/edit_rule_button.png) + +This will take you to the edit rule screen, which is the same as the new rule screen. + +![Screenshot showing an or conditional in use](images/new_rule-complete.png) + +Once you have finished editing ther rule, click the back button to go back to the rules screen. Your changes will be saved automatically. + +## Remove Rule + +To remove a rule you can either hover over its card in the rule screen and press the "x" button, or press the trash can icon in the edit rule screen. + +Either way you will be shown a remove rule confirmation dialog. Click "Remove Rule" to delete it. + +![Screenshot showing an or conditional in use](images/remove_rule-confirm.png) \ No newline at end of file diff --git a/docs/gateway/settings.md b/docs/gateway/settings.md new file mode 100644 index 0000000..54ed098 --- /dev/null +++ b/docs/gateway/settings.md @@ -0,0 +1,277 @@ +# Settings + +The settings view enables you to customise the settings of your gateway device. + +To navigate to the settings view, select the "Settings" option from the main menu. + +![Screenshot of the main menu with the "Settings" option selected](images/main_menu-settings.png) + +You will then see the settings menu, which lists the different types of settings that can be configured: + +- [Domain](#domain) +- [Network](#network) +- [Users](#users) +- [Add-ons](#add-ons) +- [Localisation](#localisation) +- [Updates](#updates) +- [Authorisations](#authorisations) +- [Experiments](#experiments) +- [Developer](#developer) + +![Screenshot of the settings view](images/settings_view.png) + +**🗒️ Note:** The available settings will vary slightly depending on which platform (hardware and operating system) you are running the gateway application on. + +## Domain + +The domain settings allow you to customise how your gateway is accessed on local and remote networks. + +![Screenshot showing the domain settings view, with a text box and checkbox to configure the local domain, and information about remote access](images/domain_settings.png) + +### Local Access + +By default, your gateway will be accessible on your local network at the "gateway.local" local domain. + +To edit the local domain type a new value into the text box and click "Update host name". + +To disable access via a local domain, un-tick the "Local Access" checkbox. + +**🔧 Technical Note:** The local domain is broadcast using mDNS/DNS-SD. Not all operating systems (e.g. some versions of Microsoft Windows) support this out of the box , so you may need to install additional software on your client device in order to access the gateway's local domain. + +### Remote Access + +The remote access section tells you whether the webthings.io remote access service is configured on this gateway, to provide a secure tunnel to remotely access the gateway over the internet using a custom subdomain. + +If the remote access service has been configured, then the custom subdomain will be displayed here. + +**🗒️ Note:** It's not currently possible to configure the remote access service after first time setup. + +**🔧 Technical Note:** For technical information about how the remote access service works, see [here](https://github.com/WebThingsIO/registration_server/blob/master/doc/flow.md). + +## Network + +Network settings allow you to configure the local networks your gateway is connected to via Ethernet and Wi-Fi. + +The Network Settings screen shows an overview of current network settings, including any IP addresses assigned to the gateway, and the name of the Wi-Fi network (if any) the gateway is connected to. + +![Screenshot showing the Network Settings view, which shows an overview of current Ethernet and Wi-Fi settings, and buttons to configure them](images/network_settings.png) + +### Ethernet + +To configure Ethernet settings, click the "Configure" button under the Ethernet section of the Network Settings view. + +By default the gateway will automatically request a local IP address from a DHCP server. + +![Screenshot of Ethernet settings with the automatic option selected](images/network_settings-ethernet-automatic.png) + +If you want to you can choose to manually set an IP address instead by choosing the "Manual (Static IP)" option. + +**⚠️ Warning:** Please only change these settings if you know what you are doing. If you configure a static IP address incorrectly, it may render the gateway inaccessible on the local network. You will then need to re-configure the network settings manually on the command line. + +![Screenshot of Ethernet settings with the manual option selected, with a form to configure a static IP address](images/network_settings-ethernet-manual.png) + +### Wi-Fi + +To configure Wi-Fi settings, click the "Configure" button under the Wi-Fi section of the Network Settings view. + +The Wi-Fi settings view will display a list of Wi-Fi networks that can be detected nearby, including their signal strength and whether they are open or secured. + +If the gateway is connected to one of these networks it will say "Connected" in green writing. + +![Screenshot of the Wi-Fi settings view, listing nearby Wi-Fi networks](images/network_settings-wifi.png) + +To connect to a Wi-Fi network, click on its entry in the list. If the network requires a password or pass key, you will be prompted to enter one before clicking "Connect". + +![Screenshot of the Wi-Fi password dialog with a text field and connect button](images/network_settings-wifi_password.png) + +**🗒️ Note:** If the gateway fails to connect to the configured Wi-Fi network, it may switch to the Wi-Fi hotspot mode from first time setup to enable you to re-connect to a Wi-Fi network. + +## Users + +The users screen allows you to manage user accounts of people who have access to the gateway. + +You will have created the first user account during first time setup, but you can add as many user accounts as you like. + +### View Users + +The users screen shows a list of user accounts and their names and email addresses. + +![Screenshot of the users screen, containing a list of user accounts on the system](images/users_screen.png) + +### Add User + +To add a user account, click the "+" button at the bottom right of the Users screen. + +You will then be prompted to enter a name, email address, password and password confirmation, before clicking "Save". + +![Screenshot showing the new user form](images/add_user.png) + +The new user will then appear on the list of users on the users screen. + +![Screenshot showing the list of two users with two users listed](images/view_users-multiple.png) + +**🗒️ Note:** Currently all user accounts are given equal and full access to the gateway, including the ability to add and remove other users. Only provide a user account to someone you trust. + +### Edit User + +To edit a user account, click the "Edit" button on its item in the list of users. + +You can change the name and email address of the user by editing the corresponding text fields. + +To change the user's password you will need to enter their current password, a new password, and confirmation of the new password. + +Once you have finished making changes, click the "Save" button. + +![Screenshot of the edit user screen, with a form to edit the name, email and password of the user](images/edit_user.png) + +#### Two-factor Authentication + +To enable two-factor authentication for the user as an additional layer of security, click the "Enable two-factor authentication" checkbox at the bottom of the Edit User screen. + +![Screenshot showing the edit user screen with the two-factor authentication checkbox ticked](images/edit_user-two_factor_auth0.png) + +You will then be presented with a QR code to scan in your two-factor authenticator app. + +If the QR code doesn't work, you can use the TOTP secret text string instead. + +![Screenshot showing the two-factor authentication option ticked, and a QR code](images/edit_user-two-factor_auth1.png) + +You will need to enter the code produced by your authenticator app in the provided text box and click "Verify" to confirm. + +![Screenshot showing a TOTP secret and a text box to enter a verification code](images/edit_user-two-factor_auth2.png) + +From this point on this user will need two-factor authentication to log in to their account. + +### Remove User + +To remove a user click the "Remove" button next to their entry in the users list. + +**⚠️ Warning:** The user will be deleted immediately, with no confirmation and no way to undo the deletion. + +## Add-ons + +The gateway has an add-ons system which enables users to add additional capabilities or customisations. There are three different types of add-ons: + +1. **Adapter Add-ons** - Add compatibility with additional types of devices or protocols +2. **Notification Add-ons** - Add additional mechanisms to send notifications to users +3. **Extension Add-ons** - Customise the user interface of the gateway + +By default only the Zigbee, Z-Wave and Web Thing adapter add-ons are installed but there are over a hundred other community-contributed add-ons to choose from. + +**🗒️ Note:** The add-ons available in the add-ons directory are contributed by the WebThings community. To learn how to create your own add-on or contribute to an existing add-on, see [Add-on Development](../hacking#add-on-development). + +### View Add-ons + +To access the add-ons screen, select the "Add-ons" option from the settings menu. This screen shows a list of currently installed add-ons including their name, description, version number, author and license. + +![Screenshot of the add-ons screen which shows a list of installed add-ons](images/add-ons_screen.png) + +**🗒️ Note:** Add-ons are automatically updated when a new version is submitted to the directory by the add-on author. + +### Add Add-on + +To install an add-on, click the "+" button at the bottom right of the add-ons screen. + +You will be presented with the latest list of available add-ons from the community maintained add-on directory. + +![Screenshot of the install add-on screen which lists available add-ons](images/add_add-on.png) + +To install one of the available add-ons, click the "Add" button on its entry in the list. + +**⚠️ Warning:** Whilst the communtity makes an effort to try to review new add-ons to check they do what they say they do, we can not guarantee that an add-on from the a third party is safe to use. It's up to users to decide whether they trust the author of any given add-on. + +If you see the word "Added" instead of an "Add" button, it means that add-on has already been installed. + +Whilst the add-on is installing you will see the word "Installing...". + +Once the add-on has been successfully installed you will see the word "Added". + +If you click the back button at the top left of the screen, you should then see the add-on you installed appear in the list. + +**💡 Tip:** You can filter the names of add-ons by typing into the "Search" box at the top of the list. + +### Enable/disable Add-on + +You can temporarily disable an add-on by clicking the "Disable" button on its entry in the add-on list, and re-enable it again by clicking "Enable". + +### Remove Add-on + +To remove an add-on click the "Remove" button. + +**⚠️ Warning:** Clicking the "remove" button will automatically remove an add-on without requiring any confirmation, which may result in the loss of data. + +### Configure Add-on + +Some add-ons have additional configuration options available via a "Configure" button. These options are unique to each add-on. + +## Localisation + +The Localisation section allows you to customise the gateway user interface to match your locale. + +![Screenshot of the localisation settings view](images/localisation_settings.png) + +Configuration options include: + +- **Country** - This is used, amongst other things, to set the country code in Wi-Fi settings +- **Timezone** - This is important to ensure that rules execute at the time you expect +- **Language** - This is used to customise the language used in the user interface +- **Units** - This is used to customise the preferred units used in the user interface + +**🗒️ Note:** The WebThings Gateway user interface is translated into different languages (34 at the last count) by the WebThings community. You can contribute to these translations [here](https://pontoon.mozilla.org/projects/webthings-gateway/). + +## Updates + +The gateway supports automatic over-the-air updates whenever a new version of the gateway application is released. + +To see what version your gateway is running, click on the "Updates" option from the Settings screen. + +![Screenshot of the updates screen](images/updates_screen.png) + +The Updates screen will tell you whether your gateway is up to date, or if a new version is available. + +It will also tell you the current version your gateway is running and when it was last updated. + +To disable automatic updates, un-tick the "Enable automatic updates" checkbox. + +**💡 Tip:** We recommend that you keep automatic updates enabled so that you are always running the latest available version, which may include security fixes. Whilst it is possible to manually upgrade the gateway from the UI yourself, the process takes some time and users sometimes incorrectly think the process has frozen and reboot the gateway, which may leave it in a broken state. + +**🗒️ Note:** This feature is currently only available for users who have installed WebThings Gateway using a Raspberry Pi OS-based image from our [website](https://webthings.io/gateway/). + +**⚠️ Warning:** The automatic update system does not currently update the underlying operating system, only the gateway application. It is the user's responsibility to keep the operating system (e.g. Raspberry Pi OS) up to date with security fixes. See the [Raspberry Pi documentation](https://www.raspberrypi.com/documentation/computers/os.html#updating-and-upgrading-raspberry-pi-os) for how to update Raspberry Pi OS. + +## Authorisations + +It is possible to authorise third party web services to access the gateway's API (application programming interface), in order for them to provide additional functionality by monitoring and controlling devices via your gateway. + +When a service requests access, you can choose whether they just monitor devices, or monitor and control them, and also choose exactly which devices they have access to. + +![Screenshot of the Authorisation Request screen with a dropdown to choose the level of access and checkboxes for each device](images/authorisation_request.png) + +To view a list of services you have authorised to access your gateway, choose the "Authorisations" option in the settings menu. + +![Screenshot of the authorisations screen with one authorisation granted](images/authorisations.png) + +You can revoke access from a given service at any time by clicking the "Revoke" button. + +## Experiments + +From time to time, the WebThings community will create new experimental features for users to try out before they are fully complete. + +To see a list of experiments to enable or disable, click the "Experiments" option in the settings menu. + +![Screenshot of the experiments view, showing there are currently no experiments available](images/experiments.png) + +## Developer + +**⚠️ Warning:** Here be dragons! + +There some advanced settings available for developers including: + +- Enabling command line access to the gateway on the local network via SSH +- Viewing internal system logs for use during debugging +- Issuing local API tokens (JSON Web Tokens) for use during development + +![Screenshot of developer settings](images/developer_settings.png) + + + diff --git a/docs/gateway/setup.md b/docs/gateway/setup.md new file mode 100644 index 0000000..5d89b28 --- /dev/null +++ b/docs/gateway/setup.md @@ -0,0 +1,54 @@ +# First Time Setup + +The first time your gateway boots it will require some configuration. + +## 1. Connect Wi-Fi (Optional) + +When the gateway starts up it will create a Wi-Fi hotspot called "**WebThings Gateway XXXX**" (where XXXX are four digits from your Raspberry Pi's MAC address). Use a smartphone, tablet or desktop computer to scan for and connect to that wireless network. + +![A screenshot from a desktop operating system showing the user selecting a Wi-Fi hotspot called WebThings Gateway 16D1](images/wifi_ssid.png) + +A captive portal page will appear, showing nearby Wi-Fi networks. + +![A screenshot showing the names of nearby Wi-Fi networks](images/connect_wifi.png) + +Select the desired network and enter a password if prompted. The "Connecting to Wi-Fi..." page should automatically disappear. + +Or to skip connecting to a Wi-Fi network (if already connected via Ethernet), click the "Skip" button (you can reconfigure Wi-Fi later from [Settings](../settings)). + +After you've connected your gateway to a wireless network, you should ensure that your smartphone, tablet or desktop computer is connected to the same Wi-Fi network and then navigate to [http://gateway.local](http://gateway.local) in your web browser to access the gateway's web interface. + +**🗒️ Notes:** + +* If you are connected to the "WebThings Gateway XXXX" Wi-Fi network but you don't see the captive portal, you can try typing "http://192.168.2.1" into your web browser's address bar to manually navigate to the page. +* As an alternative to Wi-Fi, you can connect the Raspberry Pi to your home network using an Ethernet cable and it will attempt to automatically get an IP address from your router. +* If you're not able to access "http://gateway.local" (e.g. on Microsoft Windows), you may need to look up the IP address assigned to the Raspberry Pi by your router (look for a hostname of “gateway” or a MAC address starting with “b8:27:eb”), and type that into the address bar of your web browser instead. +- If neither "http://gateway.local" or "http://{IP ADDRESS}" will load in your browser, check to make sure your computer is definitely connected to the same network you connected the gateway to. +- If you move the gateway to another location and it can no longer access your home network, it will revert to access point mode so you can connect to it and re-configure a different network. + +## 2. Register a Subdomain (Optional) + +When you load "http://gateway.local" for the first time, you will be given the option to register a free subdomain to safely access your gateway over the Internet using a secure tunnelling service. + +![A screenshot showing a form to choose a subdomain of webthings.io and enter an email address](images/choose_subdomain.png) + +Enter your choice of subdomain and an email address in case you need to retrieve your subdomain later to re-install on a new gateway. You will also need to agree to the WebThings Privacy Policy and Terms of Service in order to use the back end services provided by the community. Click “Create” and wait a few moments for the subdomain registration to complete. You should then be redirected to your new subdomain. + +**🗒️ Notes:** + +- You can choose to skip this step (either to only use the gateway locally on your home network or manually configure DNS yourself), but note that currently if you do skip this step you’ll have to re-flash the gateway in order to register a subdomain +- If you have previously registered a subdomain you want to re-use, enter the subdomain and the email address you used to register it and follow the on-screen instructions to re-claim it + +## 3. Create a User Account + +The gateway will next prompt you to create your first user account. Enter a name, email address and a password and click "Next". + +![A screenshot showing a form to enter a name, email address and password](images/create_user.png) + +**🗒️ Note:** You can create additional user accounts later. + +**Success!** + +Once your user account has been successfully created, you will be automatically logged in to the gateway and you should see an empty Things screen, ready for you to start adding devices. + +![A screenshot showing an empty screen with a main menu and an add button](images/empty_things_screen.png) diff --git a/docs/gateway/supported-hardware.md b/docs/gateway/supported-hardware.md new file mode 100644 index 0000000..d4838ca --- /dev/null +++ b/docs/gateway/supported-hardware.md @@ -0,0 +1,3 @@ +# Supported Hardware + +To see a community-maintained list of hardware known to work with WebThings Gateway, see [this wiki page](https://github.com/WebThingsIO/wiki/wiki/Supported-Hardware). \ No newline at end of file diff --git a/docs/gateway/things.md b/docs/gateway/things.md new file mode 100644 index 0000000..c94ba27 --- /dev/null +++ b/docs/gateway/things.md @@ -0,0 +1,114 @@ +# Things + +On the WebThings platform, connected devices are referred to as "things". + +## Add Thing + +To add a thing to your gateway, click the "+" button on the Things screen. This will tell the gateway to start scanning for new devices. + +**🗒️ Note:** Many smart home devices will require the user to press a pairing button of some kind in order to initiate a pairing mode. You should follow any instructions that came with your device to enable pairing mode before clicking the "+" button. + +![A screenshot showing an empty screen with a main menu and an add button](images/empty_things_screen.png) + +A preview of any discovered devices will appear on the screen. + +![A screenshot showing the add thing screen with some thing previews of devices that have been found](images/add_thing_screen-new_things.png) + +When a device has multiple capabilities (e.g. it acts as both an on/off switch and an energy monitor) you can choose the primary function to display in the user interface from a drop-down menu. + +You can also change the name of the device to something meaningful to you (e.g. "Kitchen Light") before clicking "Save" to add it to the gateway. + +If you click the back button at the top left of the screen to go back to the Things screen, you should now see an icon representing the device you added. + +![A screenshot showing an icon for a Living Room Light](images/things_screen-single_thing.png) + +**🗒️ Note:** Only the Zigbee, Z-Wave and Web Thing add-on adapters are installed by default. To support other types of devices, you will need to install additional [add-ons](../settings#add-ons). + +### Add Thing by URL + +In addition to scanning for new devices, you can manually add a new thing by its "web thing URL". That is the URL of a [Web Thing Description](https://webthings.io/api/#web-thing-description). + +**🔧 Technical Note:** Currently the gateway only supports [Web Thing Description](https://webthings.io/api/#web-thing-description)s following the legacy Mozilla format. There is a [work-in-progress add-on adapter](https://github.com/WebThingsIO/wot-adapter) for supporting W3C WoT compliant Thing Descriptions. + +To add a thing by a web thing URL, click the "Add by URL" link on the Add Thing screen. + +![A screenshot showing the Add Thing screen with the Add by URL link](images/add_thing_screen-scanning.png) + +A form will then appear with a text box into which you can paste a web thing URL. Click "Submit" to retrieve details about the Thing, then click "Save" to add it to the gateway. + +![A screenshot showing the Add Thing screen with the Add by URL link](images/add_thing_by_url.png) + +## View Things + +To view all of your things, select the "Things" option from the main menu. + +Each thing is represented by an icon. The icon shows a live overview of the current state of the thing (e.g. its on/off state or the current value of a key property). Different styles of icon are used for different types of devices. + +![A screenshot showing a collection of icons representing things](images/things_screen.png) + + +### Thing Detail + +To view the properties and actions of a thing, click on the small round detail button at the top right of a thing icon. This will navigate to its detail view. + +![A screenshot showing the detail view of a thing, including an on/off property and a brightness property](images/thing_detail.png) + +The detail view will show you all of the properties and actions associated with a device. + +#### Properties + +Properties may be read-only (e.g. a temperature reading) or writable (e.g. an on/off state which can be toggled with a switch, or a level which can be set with a slider). + +There are many different types of properties for different types of devices, which each have a specialised user interface. + +![A screenshot showing the detail view of a thing, including an on/off property, brightness, color, color temperature and color mode](images/thing_detail-dimmable_color_light.png) + +#### Actions + +Actions are represented by a button and may accept one or more input values (e.g. a percentage to fade a light to over a specified number of seconds). + +![Screenshot of showing the detail of a thing with buttons to invoke actions](images/action_and_events_things.png) + +To provide inputs to an action, click the action's button on the thing detail view and complete the fields in the form which appears before pressing the submit button. + +![A screenshot showing a form to provide inputs for an action](images/action_input.png) + +If an action doesn't require any inputs then pressing its button will immediately invoke the action. + +#### Events + +To view a log of events emitted by a thing, click the overflow menu button at the bottom right of the screen and select the "Event log" option. + +![A screenshot showing the overflow menu on the thing detail view with the "Event log" option selected](images/event_log_option.png) + +You will then be shown a live log of events being emitted by the device, including event data and timestamps. + +![A screenshot showing a collection of events represented by boxes showing an event name, data and relative timestamp](images/event_log.png) + + +**🔧 Technical note**: The gateway's adapter [add-ons](../settings#add-ons) are responsible for mapping various devices and protocols to an extensible set of "[WoT capability schemas](https://webthings.io/schemas/)". These schemas are represented in a machine-readable format via semantic annotations on a Thing Description. Thing Descriptions are then used by the gateway to generate a rich user interface for each type of device capability, property, action and event. + +## Edit Thing + +To edit a thing, select the "Edit" option from the thing detail overflow menu at the bottom right of the screen. + +![Screenshot of the thing detail overflow menu with the "Edit" option selected](images/edit_thing_option.png) + +You can then edit the name of the thing and/or its primary device type before clicking "Save" to save your changes. + +![Screenshot of the edit thing dialog with a text input to edit its name and a dropdown menu to choose the primary device type](images/edit_thing.png) + +## Remove Thing + +To remove a thing, select the "Remove" option from the thing detail overflow menu at the bottom right of the screen. + +![Screenshot of the thing detail overflow menu with the "Remove" option selected](images/remove_thing_option.png) + +You will then be asked to confirm the removal of the device from the gateway. + +![Screenshot of the confirm remove thing dialog with a remove button](images/confirm_remove_thing.png) + +**🗒️ Note:** Whilst removing a device from the gateway using the remove thing feature will remove it from the gateway user interface, it might not always fully un-pair it from the gateway at the hardware level (e.g. if using a USB dongle). Sometimes a device will have an un-pairing procedure which needs to be followed in order to full disassociate it from the gateway (e.g. involving pressing a button on the device). + + + diff --git a/docs/images/logo.svg b/docs/images/logo.svg new file mode 100644 index 0000000..47c9189 --- /dev/null +++ b/docs/images/logo.svg @@ -0,0 +1,235 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..60abb5b --- /dev/null +++ b/docs/index.md @@ -0,0 +1,27 @@ +# WebThings Documentation + +Welcome to the documentation for the [WebThings](https://webthings.io) project. + +WebThings is an open platform for monitoring and controlling devices over the web. + +## WebThings Gateway + +*Host your own private smart home.* + +[WebThings Gateway](gateway/introduction) is a software distribution for smart home hubs focused on privacy, security and interoperability. It enables you to securely monitor and control your home over the web, without a middleman. + +![Alt text](gateway/images/floorplan_view.png) + +## WebThings Framework + +*Build your own web things.* + +[WebThings Framework](framework/introduction) is a collection of re-usable software components to help developers build their own web things. + +## W3C Web of Things + +The [W3C Web of Things](wot/introduction) is the collection of open standards upon which the WebThings platform is built. + +--- + +🛟 For support, please sign up to our [forum](https://discourse.mozilla.org/c/iot), chat with us in the [#iot:mozilla.org](https://matrix.to/#/#iot:mozilla.org) channel on Matrix, or post [issues](https://github.com/WebThingsIO/gateway/issues) on GitHub. diff --git a/docs/wot/architecture.md b/docs/wot/architecture.md new file mode 100644 index 0000000..6f3caa6 --- /dev/null +++ b/docs/wot/architecture.md @@ -0,0 +1 @@ +# WoT Architecture \ No newline at end of file diff --git a/docs/wot/discovery.md b/docs/wot/discovery.md new file mode 100644 index 0000000..adbf283 --- /dev/null +++ b/docs/wot/discovery.md @@ -0,0 +1 @@ +# WoT Discovery \ No newline at end of file diff --git a/docs/wot/images/web_of_things_illustration.png b/docs/wot/images/web_of_things_illustration.png new file mode 100644 index 0000000..caaac56 Binary files /dev/null and b/docs/wot/images/web_of_things_illustration.png differ diff --git a/docs/wot/introduction.md b/docs/wot/introduction.md new file mode 100644 index 0000000..8af4be9 --- /dev/null +++ b/docs/wot/introduction.md @@ -0,0 +1,32 @@ +# W3C Web of Things + +![An illustration of a web of connected devices with the Web of Things logo at the centre](images/web_of_things_illustration.png) + +The [Web of Things](https://www.w3.org/WoT/) (WoT) is defined by a collection of specifications standardised by the [World Wide Web Consortium](https://w3.org) (W3C). + +According to the W3C, *"the Web of Things (WoT) seeks to counter the fragmentation of the IoT by using and extending existing, standardized Web technologies. By providing standardized metadata and other re-usable technological building blocks, W3C WoT enables easy integration across IoT platforms and application domains."* + +The Web of Things is to the Internet of Things what the World Wide Web is to the Internet. + +It gives URLs to physical devices in the real world to make them linkable, provides a data model to describe them and a communication protocol to interact with them. + +The Web of Things can be used as a unifying application layer for the Internet of Things, linking together multiple underlying IoT protocols using existing web technologies. + +The core normative specifications (standards) which define the Web of Things are: + +- [WoT Architecture](https://www.w3.org/TR/wot-architecture/) - Describes the building blocks of the Web of Things and how they fit together +- [WoT Thing Description](https://www.w3.org/TR/wot-thing-description/) - Defines an information model and JSON-based serialisation format for describing the capabilities of connected devices in a protocol agnostic way +- [WoT Discovery](https://www.w3.org/TR/wot-discovery/) - Defines various mechanisms for discovering web things, including a Thing Description Directory +- [WoT Profiles](https://w3c.github.io/wot-profile/) - Defines sets of prescriptive constraints called "profiles" to enable out-of-the-box interoperability between conformant web things and their consumers + +There are also some informative notes which provide additional guidance: + +- [WoT Binding Templates](https://www.w3.org/TR/wot-binding-templates/) +- [WoT Scripting API](https://www.w3.org/TR/wot-scripting-api/) +- [WoT Security and Privacy Guidelines](https://www.w3.org/TR/wot-security/) + +These specifications were designed to fulfill a collection of [Use Cases and Requirements](https://www.w3.org/TR/2022/NOTE-wot-usecases-20220307/) originally defined by the [Web of Things Interest Group](https://www.w3.org/WoT/ig/). + +In addition to the specifications written by the WoT Working Group, there is a specification being incubated by the [Web Thing Protocol Communtiy Group](https://www.w3.org/community/web-thing-protocol/) which defines a common protocol for the Web of Things called the Web Thing Protocol: + +- [Web Thing Protocol Use Cases & Requirements](https://www.w3.org/community/reports/web-thing-protocol/CG-FINAL-web-thing-protocol-requirements-20231101/) \ No newline at end of file diff --git a/docs/wot/profiles.md b/docs/wot/profiles.md new file mode 100644 index 0000000..e9e9123 --- /dev/null +++ b/docs/wot/profiles.md @@ -0,0 +1 @@ +# WoT Profiles \ No newline at end of file diff --git a/docs/wot/thing-description.md b/docs/wot/thing-description.md new file mode 100644 index 0000000..e6fc021 --- /dev/null +++ b/docs/wot/thing-description.md @@ -0,0 +1 @@ +# WoT Thing Description \ No newline at end of file diff --git a/docs/wot/web-thing-protocol.md b/docs/wot/web-thing-protocol.md new file mode 100644 index 0000000..9d72084 --- /dev/null +++ b/docs/wot/web-thing-protocol.md @@ -0,0 +1 @@ +# Web Thing Protocol \ No newline at end of file diff --git a/gateway-getting-started-guide.md b/gateway-getting-started-guide.md deleted file mode 100644 index c1e5c71..0000000 --- a/gateway-getting-started-guide.md +++ /dev/null @@ -1,94 +0,0 @@ -# Getting Started - -## WebThings Gateway for Raspberry Pi® - -[WebThings Gateway](https://webthings.io/gateway/) is a software distribution for smart home gateways which allows users to directly monitor and control their smart home over the web, without a middleman. - -### What you will need - -what you need - -1. **A [Raspberry Pi®](https://www.raspberrypi.org/products/)** single board computer and power supply (Raspberry Pi 3 recommended, with minimum 2A power supply) -2. **A microSD card** (At least 8GB, class 10 recommended) -3. **USB dongles** (see the list of [compatible dongles](https://github.com/WebThingsIO/wiki/wiki/Supported-Hardware#usb-dongles)) - -**Note:** The Raspberry Pi 3 comes with Wi-Fi and Bluetooth radios. The USB dongles are needed if you want to support other smart home protocols like Zigbee and Z-Wave. - -### 1. Download Image - -First download the latest gateway image from the [WebThings website](https://webthings.io/gateway/). - -### 2. Flash Image - -Next you will need to flash the downloaded image onto your microSD card. There are [various methods](https://www.raspberrypi.org/documentation/installation/installing-images/) of doing this but we recommend using [Etcher](https://www.balena.io/etcher/). - -etcher screenshot - -1. Open Etcher -2. Insert your SD card into an SD card reader attached to your computer -3. Select the downloaded image as the source file -4. Select your SD card as the target -5. Click "Flash!" - -Once flashing is complete, remove the microSD card. - -### 3. Boot Raspberry Pi - -plug in - -1. Insert the flashed microSD card into your Raspberry Pi -2. Plug in any USB dongles -3. Connect the power supply to boot the Pi -4. Check that the LEDs light up: red indicates power, green indicates activity -5. Wait a few minutes for the software to boot - -**Note:** On first boot the Raspberry Pi may take an additional 2-3 minutes longer to boot in order to take care of some first time setup. - -### 4. Connect Wi-Fi -Your gateway will most likely connect to the Internet and also communicate with all your devices via Wi-Fi, which needs to be set up next. - -When the gateway starts up it will create a Wi-Fi hotspot called "**WebThings Gateway XXXX**" (where XXXX are four digits from your Raspberry Pi's MAC address). Use a personal computer or smartphone to scan for and connect to that wireless network. - -Wi-Fi SSID - -A captive portal page will appear, showing nearby Wi-Fi networks. - -connect Wi-Fi - -Select the desired network and enter the password when prompted. The "Connecting to WiFi..." page will automatically disappear. - -**Notes:** -* If you are connected to the "WebThings Gateway XXXX" Wi-Fi network but you don't see the welcome screen, you can try typing http://192.168.2.1 into your web browser's address bar to manually navigate to the page. -* As an alternative to Wi-Fi, you can connect the Raspberry Pi to your home network using an Ethernet cable and it will attempt to automatically get an IP address from your router. You can then start first time setup by typing "http://gateway.local" into your web browser. -* If you move the gateway to another location and it can no longer access your home network, it will revert to access point mode so you can connect to it and re-configure a different network. - -### 5. Choose Subdomain - -After you've connected the Raspberry Pi to your wireless network, you should ensure that your laptop/tablet/smartphone is connected to the same Wi-Fi network and then navigate to **http://gateway.local** in your web browser. - -You will then be given the option to register a free subdomain to safely access your gateway over the Internet using a [secure tunnelling service](https://github.com/WebThingsIO/registration_server/blob/master/doc/flow.md). - -choose subdomain - -Enter your choice of subdomain and an email address in case you need to retrieve your subdomain later to re-install on a new gateway. Click "Create" and wait a few moments for the subdomain registration to complete. Try loading your subdomain on your smartphone or computer by loading https://SUBDOMAIN.webthings.io (where 'SUBDOMAIN' is the subdomain name you've chosen). - - -**Notes:** - * You can choose to skip this step (either to only use the gateway locally on your home network or manually configure DNS yourself), but note that currently if you do skip this step you'll have to re-flash the gateway in order to register a subdomain. - * If http://gateway.local fails to load (e.g. on Android or Windows) you can look up the IP address of the gateway on your home router and use that instead (look for a hostname of "gateway" or a MAC address starting with "b8:27:eb". - * If neither http://gateway.local or http:// will load in your browser, check to make sure your computer is definitely connected to the same Wi-Fi network you connected the gateway to. - * If you have previously registered a subdomain you want to re-use, enter the subdomain and the email address you used to register it and follow the on-screen instructions to re-claim it. - -### 6. Create User Account -Once you have registered your subdomain you should be automatically redirected to the next step of the setup process, which is to create your first user account on the gateway. This is how you'll access the gateway to discover, add, monitor and manage all your connected devices. Enter your name, email address and a password then click "Next". - -create user account - -***Note:*** You can create additional user accounts later. - -### Success! -You should then be redirected to an empty "Things" screen of the gateway where you can start to add devices. - -things screen - -See the [WebThings Gateway User Guide](./gateway-user-guide.md) to learn how to use your gateway including adding and managing smart devices, creating rules to automate your home, using logging to track data from your devices, and more. diff --git a/gateway-user-guide.md b/gateway-user-guide.md deleted file mode 100644 index 4e592d5..0000000 --- a/gateway-user-guide.md +++ /dev/null @@ -1,336 +0,0 @@ -# User Guide - -## WebThings Gateway for Raspberry Pi User Guide -[WebThings Gateway](https://webthings.io/gateway) is a software distribution for smart home gateways which allows users to directly monitor and control their smart home over the web, without a middleman. - -This guide assumes you have already followed the [Getting Started Guide](https://webthings.io/docs/gateway-getting-started-guide.html) to bring your gateway online. - -## I. Introduction - -Congratulations on choosing to set up your own private Smart Home Gateway. This guide provides an overview of -the WebThings Gateway. This guide covers release version 0.12. Hereafter we will -usually just refer to it as the "gateway". - -The gateway lets you directly monitor and control your home over the web. Unlike many smart home hubs and connected -IoT devices on the market, your data is not stored or processed in the cloud. It stays in your home on the gateway. -The gateway can often bypass the need for you to purchase an IoT hub for each brand, and instead of downloading a -different app for each brand, you can manage everything from one place, using any web browser. - -This guide will explain how to customize your gateway, including connecting smart home devices, creating rules to automate -your home, and a few additional tips. - -The following image shows a typical collection of smart home devices, the top row shows the Raspberry Pi, power supply -and a Zigbee USB dongle. The bottom row shows a door sensor, smart plugs, smart bulb, and motion sensor. - -smart home devices - -## II. Smartphone Application Convenience - -Currently there is no specific smartphone application for the gateway, but you can load your unique gateway url into a smartphone browser application and save it to your home screen, which makes it work just like any other application. - -If you use the WebThings Cloud tunneling service, your gateway url will be of the form `[your_subdomain].webthings.io`. - -We recommend that you **bookmark** the web address on all devices that you have access to from home. -It is also handy to save your WebThings Gateway as a **web application on the home screen** of your phones and tablets. - -On Android phones/tablets: -* In Firefox: Select the "add to home" icon in the address bar (circled in red) to add an app icon to your home screen. -* In Chrome: Select "Add Things to Home screen". - -firefox add to homefirefox as web app - -On iPhones and iPads: -* In Safari: Select the Share icon, and then "Add to Home Screen". -* (Note that iOS does not currently support an "add to home screen" function for Firefox or Chrome browsers.) - -safari sharesafari add to home - -## III. Adding and Managing Smart Home Devices - -The WebThings Gateway has an add-on system that lets it understand how different connected devices and services ("things") operate. For each type of device (or service) you'll need to install and configure the proper add-on so the gateway can use it to discover and connect to them as things. - -A few add-ons are pre-configured as part of the standard gateway installation, notably those required for common smart home devices using Zigbee and Z-Wave communications technologies. To make sure the gateway can discover all your devices it is best to first make sure all the right add-ons are installed and enabled. - -### Add-ons - -From the Main Menu, go to Settings and select Add-ons. From the Add-ons page that appears, click on the "+" icon to bring up an alphabetical list of installable add-ons. Add any and all add-ons that correspond to smart devices you have in your home and wish to manage with the gateway, as well as services you may wish to use with your gateway. - -As an example, the Weather add-on allows your gateway to connect to an open weather information service and display current conditions. It is included in the list of available add-ons, and can be added by clicking "+ Add": - -weather addon - -Click on the left arrow icon to return to the list of installed add-ons. Find the Weather add-on and click "Configure": - -weather addon configure - -Configure the weather add-on: -* Enter the name of the location for which you want to track weather. -* Enter the latitude and longitude (which you can find on sites like www.latlong.net) -* You can use the default OpenWeatherMap API key - -weather addon settings - -Return to the main Things page (https://SUBDOMAIN.webthings.io/things) and click the "+" icon to add a new thing. Scanning for new devices should discover the Weather thing with the location name you specified. Click "Save". - -add weather thing - -Now you can view weather data by going to the main Things page to see the installed weather thing: - -weather thing - -### Scan For and Add Smart Devices - -Now that your gateway is setup it's easy to discover connected devices in the environment around you. By default the Raspberry Pi supports Wi-Fi, Bluetooth and Ethernet. Additional accessories may be purchased to increase the number of devices your gateway can connect to. - -Pick a device to add and prepare it for pairing. Typical preparation steps for Zigbee and Z-Wave devices are as follows: -* Smart bulb: screw into a light fixture that it is turned on (bulb should be lit when ready for pairing) -* Smart plug: plug into an outlet -* Other powered devices: plug in and turn on -* Battery-operated devices such as door/window sensors, motion detectors, pushbuttons, dimmer switches, leak detectors, -temperature sensors, and more: remove tab from battery, or plug in battery, to power on - -sensor battery tab - -**TIP**: Some devices come pre-paired with controllers or IoT hubs. First follow the manufacturers instructions to do -a **factory reset** on those devices before attempting to pair them with your WebThings Gateway. Refer to the appendix -and to the wiki for more information. - -When you are ready to add devices to your WebThings Gateway, we recommend that you provision devices one at a time. - -From the main "Things" page, select the plus -button at the bottom right corner. -The gateway will begin scanning to discover unprovisioned and unconfigured devices that are nearby. - -scan things - -When a new device is found, it will appear on the Things scan page. Rename the device, then select -'Save' to add it, and 'Done' when you are finished. - -save things - -**TIP**: When naming your smart devices, we recommend using a name that helps you remember where they are -located in your home, e.g. "Bedroom Light". - -Repeat these discovery steps for each device. Powering them up and scanning for them one at a time helps you -identify each device. - -### Control Your Things - -First learn how to monitor and control each device by checking out its capabilities. Then in the next section -you can learn to create rules to automate interactions between devices. - -Devices are displayed on the Things screen and the Floorplan screen. You can toggle light bulbs and smart plugs -on and off by directly clicking on the device icon. You can also see the current state of devices such as -door sensors and motion detectors, from these screens. - -things screen - -To view and control additional details, click the bubble icon -toward the top-right of a device icon. A detailed thing page should open. - -detailed things screen - -To edit a device's name or remove it altogether, select -the edit icon in the bottom right-hand corner. - -edit menu - -## IV. Rules: Automate Your Home - -Now that your WebThings Gateway is set up and your smart things are connected, you can start automating -your home for your convenience by creating 'Rules'. Practice creating a rule by following the next few steps. - -### Create a Rule - -Navigate to the "Rules" page from the main menu. Click the plus icon -in the lower right corner to create a new rule. In Rule creation, the basic logic is: if (A), then (B). Optionally, -you can change "if" to "while" and combine multiple inputs for (A), and take action against multiple outputs for (B). - -new rule - -Let's start by grabbing our input: time. Drag the 'clock' from the bottom of the screen to the left side of the Rule space. -Since we want something to occur at 10pm, set the time to '10:00 PM'. - -clock as input - -Next we select our output: a smart bulb named "Bedroom Light". Drag the light you want to turn off at 10pm to the right -side of the Rule space. - -light action - -To complete the rule, select the desired property of the smart light that you want to set at 10pm. -In this example, we want the bedroom light to turn "Off" at 10pm. Go to the light's drop down menu and select 'Off'. -The clock and light bulb rectangles should now be connected by a black line, and the "If" statement under -your Rule name should be updated to reflect the logic of this rule. - -completed rule - -In the top left hand corner, click the tiny pencil near "Rule Name" to edit the name of your rule. For example, -you can name this rule "At 10pm, turn off bedroom light". -For clock-based rules, the "If" statement below the name is appropriate logic. For other situations, such as -turning on a light only when a door is open, you can change it to "While" instead. When you have more than -one input parameter, you can select "And" or "Or" as the logical condition to tie together the input parameters. - -Click on the back-arrow button in the upper left-hand corner of the Rule space (next to the name), -to save the rule and return to the main Rule overview page. - -### View/Edit, Disable/Enable, or Remove a Rule - -From the main Rules view, each rule is represented by a rectangle. -* View/Edit. You can view or change a rule by hovering over the middle of the rectangle and selecting the "Edit" button. - -rule mouse over - -* Disable/Enable. You can disable a rule by toggling the "switch" element to the left, which will turn the circle color -to grey. You can re-enable the rule by toggling the switch element back to the right, turning the circle back to white. - -enable or disable rule - -* Remove. To remove (permanently delete) a rule, hover over the rule rectangle and click on the "(x)" in the upper -right-hand corner. - -remove rule - -## V. Using Logging - -The logging page is visible in the main navigation menu. Any devices that can be logged will be visible from -the configuration screen, accessed by clicking the plus icon in the lower right corner. Select the device you want to log, the property you want to log, and duration of log data you want to store on your gateway. - -log temp - -## VI. Floorplan: Map the Location of Your Devices - -The Floorplan allows you to view your devices as they are positioned within your home. It shows all your devices, -consistent with what you would see on the Things page, but it lets you see their states mapped over the layput of -your home. You can still click an icon to change its state, the same as you would on the Things page. However, -one interaction difference is that you need to click-and-hold on an icon to open the thing's detailed view. - -### Create a Floorplan - -First sketch a floorplan of your home, and save it as a digital image. You can draw one by hand and take a picture of it, -or use an illustrator tool. (If you take a picture of the floorplan using your smartphone, you can upload the image -directly to your gateway from the phone's browser.) - -sketched floorplan - -**TIP**: Save your digital drawing as an SVG file with white lines and a transparent background, using a tool like Inkscape or Sketch, for a minimalist look. - -svg floorplan - -### Upload Floorplan - -Click on the pencil icon pencil in the lower right corner of the floorplan -page to enter edit mode. An "upload file" button will appear -- click on it to select the floorplan image to be uploaded. - -upload floorplan - -After the floorplan image is uploaded, make sure you are still in edit mode, and then drag the thing icons from the top -of the page onto the floorplan. Click the check mark checkmark -in the lower right corner when done. - -position things on floorplan - -## VII. More Add-Ons: Further Extend your Gateway's Capabilities - -The gateway has an add-on system so that you can extend its capabilities. A few add-ons are installed by default -(Web Thing, Zigbee, and Z-Wave) so that your gateway will work with a large number of commercial devices right -out of the box. However, you can add support for additional devices if they are supported by an add-on. You'll -find the Add-ons page under Settings. - -### Locate and Install More Add-Ons As Needed - -From the Settings menu, select Add-Ons. - -addons - -To enable more Add-Ons, click the "(+)" button in the lower right to browse the add-on list, -then select ` + Add` to enable any additional add-ons. For example, if you have TP-Link or HomeKit compatible -devices at home, you can install their add-ons, then discover and pair the devices so that they can be managed -by your WebThings Gateway. - -select addon - -New add-ons will continue to be developed to enable control of newly supported devices, so check back periodically -to scan new add-ons in the list. You can submit requests for additional device support in the issues tab of the -[gateway software development site](https://github.com/WebThingsIO/addon-list/issues). - -## VIII. Additional Settings - -Browse the other pages listed under the Settings menu to find additional configuration and capabilities. - -settings menu - -### Domain - -The default localhost name is gateway.local, but you can change it to match your subdomain or choose a different name. - -localhost name - -### Network - -A Raspberry Pi gateway can connect to your local network using Wi-Fi or Ethernet. On the network configuration page you can -see which settings are active, and click either option to change the configuration. Be careful with these settings, because -if your gateway loses access to the local network, your ability to access the UI in a web browser will stop working. - -network settings - -### Users - -You can add as many user accounts as you like, so that everyone has their own unique login. Although all users currently have the same access and control privileges, a future feature may be to allow lesser privileges to some users, -such as children or guests. - -user accounts - -Click the "(+)" icon to provision more user accounts. - -add user - -### Updates - -Assuming your gateway is connected to the Internet, system updates will be applied automatically when a new -stable release is ready. - -updates - -### Authorizations - -Authorizations are enabled in "Settings" by selecting "Developer => Create local authorization". This page shows -whether or not an authorization has been enabled. - -authorizations - -### Experiments - -You can try out experimental new features, if available, by enabling them in Experiments. - -### Developer - -On the "Developer" page you can enable SSH, for connecting directly to the Raspberry Pi console. The default -username is "pi", and the default password is "raspberry". If you decide to enable SSH, we recommend that you -immediately SSH into the Raspberry Pi to change the default password. Type the password command `$ passwd` and follow the prompts -to change the pi user's password. - -developer menu - -Click "View Internal Logs" to see raw logs displayed in your browser. - -view logs - -Click "Create local authorization" to establish a secure web token that can be exchanged with 3rd party -applications and services that you may want to enable, or simply for accessing the data using your own -development tools. - -create auth - -## IX. Support - -For support, please sign up to our [forum](https://discourse.mozilla.org/c/iot), join us on [Matrix](https://chat.mozilla.org) in the #iot channel, or post issues on [GitHub](https://github.com/WebThingsIO/gateway/issues). - -## Appendix: Tips on Pairing and Unpairing Smart Devices - -Although you typically can follow manufacturer instructions to pair and unpair devices, there are additional tricks to -discovering devices. Some devices have a "chain link" or other button that you should click when you are ready to scan -for the new device. Other products have reset buttons that you have to hold for some period of time to reset the device. -Still others require multiple power cycles, double-button presses and various schemes. Unfortunately there is no common -approach across a broad spectrum of device makers! Our [wiki](https://github.com/WebThingsIO/wiki/wiki) will likely be -your best bet to see methods that have worked for us. diff --git a/images/choose_subdomain.png b/images/choose_subdomain.png deleted file mode 100644 index 83a9b7c..0000000 Binary files a/images/choose_subdomain.png and /dev/null differ diff --git a/images/connect_wifi.png b/images/connect_wifi.png deleted file mode 100644 index 38aaf8d..0000000 Binary files a/images/connect_wifi.png and /dev/null differ diff --git a/images/create_user_account.png b/images/create_user_account.png deleted file mode 100644 index 9dd571a..0000000 Binary files a/images/create_user_account.png and /dev/null differ diff --git a/images/image10.png b/images/image10.png deleted file mode 100644 index 5c189a2..0000000 Binary files a/images/image10.png and /dev/null differ diff --git a/images/image11.png b/images/image11.png deleted file mode 100644 index d6d96cc..0000000 Binary files a/images/image11.png and /dev/null differ diff --git a/images/image12.png b/images/image12.png deleted file mode 100644 index 85070e5..0000000 Binary files a/images/image12.png and /dev/null differ diff --git a/images/image13.png b/images/image13.png deleted file mode 100644 index 2b2aa2b..0000000 Binary files a/images/image13.png and /dev/null differ diff --git a/images/image14.png b/images/image14.png deleted file mode 100644 index c46f774..0000000 Binary files a/images/image14.png and /dev/null differ diff --git a/images/image17.png b/images/image17.png deleted file mode 100644 index 4695b3f..0000000 Binary files a/images/image17.png and /dev/null differ diff --git a/images/image18.png b/images/image18.png deleted file mode 100644 index eb9e1ce..0000000 Binary files a/images/image18.png and /dev/null differ diff --git a/images/image2.png b/images/image2.png deleted file mode 100644 index 2436b21..0000000 Binary files a/images/image2.png and /dev/null differ diff --git a/images/image20.png b/images/image20.png deleted file mode 100644 index 6e40615..0000000 Binary files a/images/image20.png and /dev/null differ diff --git a/images/image21.png b/images/image21.png deleted file mode 100644 index 64f08fd..0000000 Binary files a/images/image21.png and /dev/null differ diff --git a/images/image23.png b/images/image23.png deleted file mode 100644 index 4a62a95..0000000 Binary files a/images/image23.png and /dev/null differ diff --git a/images/image24.png b/images/image24.png deleted file mode 100644 index 2fc24c1..0000000 Binary files a/images/image24.png and /dev/null differ diff --git a/images/image26.png b/images/image26.png deleted file mode 100644 index 74e29fe..0000000 Binary files a/images/image26.png and /dev/null differ diff --git a/images/image27.png b/images/image27.png deleted file mode 100644 index 7187efe..0000000 Binary files a/images/image27.png and /dev/null differ diff --git a/images/image28.png b/images/image28.png deleted file mode 100644 index 7eda222..0000000 Binary files a/images/image28.png and /dev/null differ diff --git a/images/image29.png b/images/image29.png deleted file mode 100644 index 15e9e05..0000000 Binary files a/images/image29.png and /dev/null differ diff --git a/images/image3.png b/images/image3.png deleted file mode 100644 index 1a94dc8..0000000 Binary files a/images/image3.png and /dev/null differ diff --git a/images/image30.png b/images/image30.png deleted file mode 100644 index 953ef62..0000000 Binary files a/images/image30.png and /dev/null differ diff --git a/images/image32.png b/images/image32.png deleted file mode 100644 index f46c5bb..0000000 Binary files a/images/image32.png and /dev/null differ diff --git a/images/image33.png b/images/image33.png deleted file mode 100644 index e5040c1..0000000 Binary files a/images/image33.png and /dev/null differ diff --git a/images/image34.png b/images/image34.png deleted file mode 100644 index 1d49bb8..0000000 Binary files a/images/image34.png and /dev/null differ diff --git a/images/image35.png b/images/image35.png deleted file mode 100644 index cbadeb5..0000000 Binary files a/images/image35.png and /dev/null differ diff --git a/images/image36.jpg b/images/image36.jpg deleted file mode 100644 index ba4484b..0000000 Binary files a/images/image36.jpg and /dev/null differ diff --git a/images/image37.png b/images/image37.png deleted file mode 100644 index c8184d0..0000000 Binary files a/images/image37.png and /dev/null differ diff --git a/images/image40.png b/images/image40.png deleted file mode 100644 index 9cb3c1d..0000000 Binary files a/images/image40.png and /dev/null differ diff --git a/images/image41.png b/images/image41.png deleted file mode 100644 index 41bbfd1..0000000 Binary files a/images/image41.png and /dev/null differ diff --git a/images/image42.png b/images/image42.png deleted file mode 100644 index 047b034..0000000 Binary files a/images/image42.png and /dev/null differ diff --git a/images/image45.png b/images/image45.png deleted file mode 100644 index 4ae74b4..0000000 Binary files a/images/image45.png and /dev/null differ diff --git a/images/image46.png b/images/image46.png deleted file mode 100644 index 11fa77d..0000000 Binary files a/images/image46.png and /dev/null differ diff --git a/images/image47.png b/images/image47.png deleted file mode 100644 index f81bded..0000000 Binary files a/images/image47.png and /dev/null differ diff --git a/images/image48.png b/images/image48.png deleted file mode 100644 index f0ff1e3..0000000 Binary files a/images/image48.png and /dev/null differ diff --git a/images/image49.png b/images/image49.png deleted file mode 100644 index a08d258..0000000 Binary files a/images/image49.png and /dev/null differ diff --git a/images/image50.png b/images/image50.png deleted file mode 100644 index 45b6e7a..0000000 Binary files a/images/image50.png and /dev/null differ diff --git a/images/image51.png b/images/image51.png deleted file mode 100644 index 6c9e11d..0000000 Binary files a/images/image51.png and /dev/null differ diff --git a/images/image53.png b/images/image53.png deleted file mode 100644 index aa9cdc1..0000000 Binary files a/images/image53.png and /dev/null differ diff --git a/images/image6.jpg b/images/image6.jpg deleted file mode 100644 index 129117a..0000000 Binary files a/images/image6.jpg and /dev/null differ diff --git a/images/image7.png b/images/image7.png deleted file mode 100644 index 335213c..0000000 Binary files a/images/image7.png and /dev/null differ diff --git a/images/log-temp.png b/images/log-temp.png deleted file mode 100644 index aa95546..0000000 Binary files a/images/log-temp.png and /dev/null differ diff --git a/images/network.png b/images/network.png deleted file mode 100644 index 6dc97a0..0000000 Binary files a/images/network.png and /dev/null differ diff --git a/images/plug_in.png b/images/plug_in.png deleted file mode 100644 index 0fc9f4a..0000000 Binary files a/images/plug_in.png and /dev/null differ diff --git a/images/settings.png b/images/settings.png deleted file mode 100644 index dab6d4c..0000000 Binary files a/images/settings.png and /dev/null differ diff --git a/images/things_screen.png b/images/things_screen.png deleted file mode 100644 index 3a01e56..0000000 Binary files a/images/things_screen.png and /dev/null differ diff --git a/images/weather_addon_add.png b/images/weather_addon_add.png deleted file mode 100644 index 5cf9e1c..0000000 Binary files a/images/weather_addon_add.png and /dev/null differ diff --git a/images/weather_addon_config.png b/images/weather_addon_config.png deleted file mode 100644 index 2dc961f..0000000 Binary files a/images/weather_addon_config.png and /dev/null differ diff --git a/images/weather_addon_configuration.png b/images/weather_addon_configuration.png deleted file mode 100644 index 5a3ffb9..0000000 Binary files a/images/weather_addon_configuration.png and /dev/null differ diff --git a/images/weather_thing.png b/images/weather_thing.png deleted file mode 100644 index 6a15ce7..0000000 Binary files a/images/weather_thing.png and /dev/null differ diff --git a/images/weather_thing_add.png b/images/weather_thing_add.png deleted file mode 100644 index 0874213..0000000 Binary files a/images/weather_thing_add.png and /dev/null differ diff --git a/images/what_you_need.png b/images/what_you_need.png deleted file mode 100644 index 9f95967..0000000 Binary files a/images/what_you_need.png and /dev/null differ diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..3e39633 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,34 @@ +site_name: WebThings Documentation +site_url: https://webthings.io/docs +site_description: 'Documentation for the WebThings platform' +nav: + - 'WebThings Gateway': + - 'Introduction': 'gateway/introduction.md' + - 'Installation': 'gateway/installation.md' + - 'First Time Setup': 'gateway/setup.md' + - 'Log In': 'gateway/log-in.md' + - 'Things': 'gateway/things.md' + - 'Rules': 'gateway/rules.md' + - 'Logs': 'gateway/logs.md' + - 'Floorplan': 'gateway/floorplan.md' + - 'Settings': 'gateway/settings.md' + - 'Log Out': 'gateway/log-out.md' + - 'Supported Hardware': 'gateway/supported-hardware.md' + - 'Development': 'gateway/hacking.md' + - 'WebThings Framework': + - 'Introduction': 'framework/introduction.md' + - 'Node.js': 'framework/node-js.md' + - 'Python': 'framework/python.md' + - 'Java': 'framework/java.md' + - 'Rust': 'framework/rust.md' + - 'Arduino': 'framework/arduino.md' + - 'MicroPython': 'framework/micropython.md' + - 'W3C Web of Things': + - 'Introduction': 'wot/introduction.md' +theme: + name: readthedocs + logo: 'images/logo.svg' + hightlightjs: true + hljs_style: atom-one-dark +extra_css: + - css/style.css