View on GitHub

WebThings Documentation

A guide to using and developing for the WebThings IoT Platform

Getting Started

WebThings Gateway for Raspberry Pi®

WebThings 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® 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)

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.

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.

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.


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.


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.

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 (where ‘SUBDOMAIN’ is the subdomain name you’ve chosen).


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.


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 including adding and managing smart devices, creating rules to automate your home, using logging to track data from your devices, and more.