View on GitHub

Mozilla WebThings Documentation

A guide to using the WebThings Gateway and WebThings Framework

Getting Started

WebThings Gateway for Raspberry Pi®

WebThings Gateway is a software distribution for smart home gateways which allows users to directy monitor and control their smart home over the web, without a middleman.

What you will need

What you need

  1. A Raspberry Pi® 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 adapters)

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 Mozilla IoT website.

2. Flash Image

Next you will need to flash the downloaded image onto your microSD card. There are various methods of doing this but we recommend using Etcher.

  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

Note: On first boot the Raspberry Pi may take 2-3 minutes to boot.

4. Connect Wi-Fi

When the gateway starts up it will create a Wi-Fi hotspot called “WebThings Gateway XXXX” (where XXXX are four digits from your Pi’s MAC address). Connect to that Wi-Fi hotspot using your desktop/laptop computer, smartphone or tablet.

Once connected you should see the WebThings Gateway welcome screen which will then scan for nearby Wi-Fi networks.

Connect Wi-Fi

Select your home network from the list and enter your Wi-Fi password to connect.


5. Choose Subdomain

Once you have connected the 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 provided by Mozilla.

Choose subdomain

Enter your choice of subdomain and an email address in case you need to retrieve it later, then click “Create”.


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. Enter your name, email address and a password then click “Next”.

Create user account

Note: You can create additional user accounts later.


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 to learn how to use your gateway.