WebThings Gateway for Raspberry Pi User Guide
WebThings Gateway by Mozilla 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 to bring your gateway online.
Congratulations on choosing to set up your own private Smart Home Gateway. This guide provides an overview of what is currently referred to as the “WebThings Gateway” by Mozilla. This guide covers release version 0.8. 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, experimenting with voice and text-based commands, 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.
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 Mozilla’s tunneling service, your gateway url will be of the form
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 Things 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”.
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.)
III. Adding and Managing Smart Home Devices
Scan For and Add Smart Devices
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
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 Mozilla gateway. Refer to the appendix and to the wiki for more information.
When you are ready to add devices to your Things Gateway, we recommend that you provision devices one at a time.
From the main “Things” page, select the button at the bottom right corner. The gateway will begin scanning to discover unprovisioned and unconfigured devices that are nearby.
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.
TIP: When naming your smart devices, we recommend using a name that helps you remember where they are located in your home. For example, “Bedroom Light”. Choose simple names that will be easy to remember and use if you want to command and control your home using voice commands.
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.
To view and control additional details, click the icon toward the top-right of a device icon. A detailed thing page should open.
To edit a device’s name or remove it altogether, select the icon in the bottom right-hand corner.
IV. Rules: Automate Your Home
Now that your Mozilla Things 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 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).
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 ‘10pm’.
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.
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.
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.
- 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.
- Remove. To remove (permanently delete) a rule, hover over the rule rectangle and click on the “(x)” in the upper right-hand corner.
V. 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.)
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.
Click on the pencil icon 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.
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 in the lower right corner when done.
VI. Add-Ons: Extend your Gateway’s Capabilities
The gateway has an add-ons 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 boost support for additional devices if they are supported by an Add-on. You’ll find the Add-on page under Settings.
Locate and Install More Add-Ons As Needed
From the Settings menu, select Add-Ons.
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 Mozilla gateway.
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.
You can try out experimental new features, like the Smart Assistant, and Logging, by enabling them in Experiments.
Enable Smart Assistant and Logging
From the Settings menu, select Experiments, and then check the boxes to enable the Smart Assistant and Logging.
Using the Smart Assistant
Once enabled, the smart assistant page can be selected from the main navigation menu. It lets you use voice and messaging commands to control the things in your home. The same commands are possible whether using voice or typing text input.
The web interface shows both typed and spoken commands that were made recently, as well as the result of the command. If a portion of a command that you spoke was misinterpreted, or just missing, try again. Remember to speak loud and clear near your PC’s microphone.
You can give it commands like “Turn the kitchen light on” and it will respond to you to confirm the action. So far it can understand a basic set of commands to turn devices on and off, set levels, set color and set color temperatures.
The first time you click on the microphone icon, your browser will ask for permission to use your computer’s microphone. From the popup dialog, click the “Remember this decision” checkbox, then select “Allow”.
Note that in the 0.8 gateway release, browser-based voice commands are processed using Google’s voice assistant API, so the audio strings are processed in the cloud. The speech-to-text result is passed back to your gateway. If you instead type a command into the text field of the smart assistant screen, those commands are processed locally and do not require a connection to the Internet.
Once enabled, 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.
VIII. Additional Settings
Browse the other pages listed under the Settings menu to find additional configuration and capabilities.
The default localhost name is gateway.local, but you can change it to match your subdomain or choose a different name.
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.
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 will be to allow lesser privileges to some users, such as children or guests.
Click the “(+)” icon to provision more user accounts.
The gateway supports a unique and flexible Add-on framework that helps users tie legacy devices, non-IP devices, and other non-standard devices into the web thing API framework. Only three add-ons are installed by default, and the rest must be added manually by the user. Because the add-on upgrades are independent from the core gateway application, they can be updated at any time.
Click the “(+)” icon to install optional add-ons.
Some add-ons require configuration in order to function (e.g., Pulse, Weather, ONVIF). Others work as soon as they are added (e.g., Virtual Things).
The Adapters page shows which of the Add-ons are currently installed and active. Go to the Add-ons page to add or remove adapters that are shown on this page.
Assuming your gateway is connected to the Internet, system updates will be applied automatically when a new stable release is ready. New versions are being released approximately quarterly.
Authorizations are enabled in “Settings” by selecting “Developer => Create local authorization”. This page shows whether or not an authorization has been enabled.
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 RPi to change the default password. Type the password command
$ passwd and follow the prompts
to change the pi user’s password.
Click “View Logs” to see raw logs displayed in your browser.
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.
For support, please sign up to our IoT Discourse forum (https://discourse.mozilla.org/c/iot) or email email@example.com or join us on Mozilla IRC #iot channel or post issues on github.
Appendix: Tips on Pairing and Unpairing Smart Devices
Although you typcially 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 supported devices wiki will likely be your best bet to see methods that have work for us.