Docs v2

.gitignore

@@ -1,2 +1,2 @@
 /Gemfile.lock
-/_site/
+/site/

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.

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;
+}

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 <Arduino.h>
+    #include <Thing.h>
+    #include <WebThingAdapter.h>
+
+    #ifdef ESP32
+    #include <analogWrite.h>
+    #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<JsonObject>();
+    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<JsonObject>();
+    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);
+    }
+
+
+```

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/).*