View on GitHub

Mozilla WebThings Documentation

A guide to using the WebThings Gateway and WebThings Framework

User Guide

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.

I. Introduction

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.

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 Mozilla’s tunneling service, your gateway url will be of the form [your_subdomain]

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:

firefox add to homefirefox as web app

On iPhones and iPads:

safari sharesafari add to home

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:

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 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 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. 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.

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 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 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 ‘10pm’.

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.

rule mouse over

enable or disable rule

remove rule

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

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

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.

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.

VII. Experiments

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.

enable experiments

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.

smart assistant

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.

Using Logging

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.

log temp

VIII. Additional Settings

Browse the other pages listed under the Settings menu to find additional configuration and capabilities.

settings menu


The default localhost name is gateway.local, but you can change it to match your subdomain or choose a different name.

localhost 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.

network settings


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.

user accounts

Click the “(+)” icon to provision more user accounts.

add user


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.

add-on discovery

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

add-on config


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.

developer menu

Click “View 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 IoT Discourse forum ( or email 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.