• Stars
    star
    2,599
  • Rank 17,629 (Top 0.4 %)
  • Language
    TypeScript
  • License
    Mozilla Public Li...
  • Created over 7 years ago
  • Updated 8 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

WebThings Gateway

WebThings Gateway

Build Status codecov dependencies devDependencies license

Web of Things gateway.

Installation

  • If you have a Rasberry Pi, the easiest way to use the gateway is to download and flash a pre-built software image to an SD card.
  • If you prefer to use Docker, we have a prebuilt Docker image available here, for both ARM and amd64. You can also build your own image from this repository.
  • On Fedora, Debian, Raspberry Pi OS, or Ubuntu, you can install the relevant .rpm or .deb package from the releases page.
  • On Arch Linux, you can install the webthings-gateway AUR package. The PKGBUILD for this package can also be seen here.
  • Otherwise, you can build it from source yourself (see below).

Documentation

Community

Prerequisites for Building

Install OS

(If you're just installing on your PC, you can skip this step).

If you're installing on a Raspberry Pi then you may need to set up the OS on the Raspberry Pi first. See here for instructions.

Install Dependencies

Ubuntu/Debian Linux

$ sudo apt update
$ sudo apt install \
    autoconf \
    build-essential \
    curl \
    git \
    libbluetooth-dev \
    libboost-python-dev \
    libboost-thread-dev \
    libffi-dev \
    libglib2.0-dev \
    libpng-dev \
    libudev-dev \
    libusb-1.0-0-dev \
    pkg-config \
    python-six \
    python3-pip
$ sudo -H python3 -m pip install git+https://github.com/WebThingsIO/gateway-addon-python#egg=gateway_addon

Fedora Linux

$ sudo dnf --refresh upgrade
$ sudo dnf group install "C Development Tools and Libraries"
$ sudo dnf install \
    autoconf \
    bluez-libs-devel \
    boost-devel \
    boost-python2-devel \
    boost-python3-devel \
    curl \
    git \
    glib2-devel \
    libffi-devel \
    libpng-devel \
    libudev-devel \
    libusb1-devel \
    pkgconfig \
    python2-pip \
    python3-pip
$ sudo -H python2 -m pip install six
$ sudo -H python3 -m pip install git+https://github.com/WebThingsIO/gateway-addon-python#egg=gateway_addon

macOS

$ brew update
$ brew install \
    autoconf \
    libffi \
    pkg-config
$ sudo -H python2 -m pip install six
$ sudo -H python3 -m pip install git+https://github.com/WebThingsIO/gateway-addon-python#egg=gateway_addon

Install Node.js

nvm (Recommended)

nvm allows you to easily install different versions of node. To install nvm:

$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.2/install.sh | bash

Reinitialize your terminal session.

$ . ~/.bashrc

Manual

(If you already installed node via nvm you can skip this step)

Follow the directions from NodeJS to install on your platform.

Set up Bluetooth permissions (Linux only)

The following is required in order to let node and python3 use the Bluetooth adapter.

$ sudo setcap cap_net_raw+eip $(eval readlink -f `which node`)
$ sudo setcap cap_net_raw+eip $(eval readlink -f `which python3`)

Download and Build Gateway

  • Clone the GitHub repository (or fork it first):

    $ git clone https://github.com/WebThingsIO/gateway.git
    
  • Change into the gateway directory:

    $ cd gateway
    
  • If you have chosen to install nvm above, install and use an LTS version of node and then set the default version. The .nvmrc file will be used by nvm to determine which version of node to install.

    $ nvm install
    $ nvm use
    $ nvm alias default $(node -v)
    
  • Verify that node and npm have been installed:

    $ node --version
    v10.23.0
    $ npm --version
    6.14.9
    

    Note: these versions might differ from the LTS version installed locally.

  • Install dependencies:

    $ npm ci
    
  • Add Firewall exceptions (Fedora Linux Only)

    $ sudo firewall-cmd --zone=public --add-port=4443/tcp --permanent
    $ sudo firewall-cmd --zone=public --add-port=8080/tcp --permanent
    $ sudo firewall-cmd --zone=public --add-port=5353/udp --permanent
    
  • Set up domain:

    • If you plan to use the provided tunneling service to set up a _.webthings.io domain:

      • Start the web server:

        $ npm start
        
      • Load http://localhost:8080 in your web browser (or use the server's IP address if loading remotely). Then follow the instructions on the web page to set up domain and register. Once this is done you can load https://localhost:4443 in your web browser (or use the server's IP address if loading remotely).

    • If you plan to use your own SSL certificate:

      • The HTTPS server looks for privatekey.pem and certificate.pem in the ssl sub-directory of the userProfile directory specified in your config. You can use a real certificate or generate a self-signed one by following the steps below.

        $ WEBTHINGS_HOME="${WEBTHINGS_HOME:=${HOME}/.webthings}"
        $ SSL_DIR="${WEBTHINGS_HOME}/ssl"
        $ [ ! -d "${SSL_DIR}" ] && mkdir -p "${SSL_DIR}"
        $ openssl genrsa -out "${SSL_DIR}/privatekey.pem" 2048
        $ openssl req -new -sha256 -key "${SSL_DIR}/privatekey.pem" -out "${SSL_DIR}/csr.pem"
        $ openssl x509 -req -in "${SSL_DIR}/csr.pem" -signkey "${SSL_DIR}/privatekey.pem" -out "${SSL_DIR}/certificate.pem"
        
      • Start the web server:

        $ npm start
        
      • Load https://localhost:4443 in your web browser (or use the server's IP address if loading remotely). Since you're using a self-signed certificate, you'll need to add a security exception in the browser.

Browser Support

The Gateway requires a browser that supports:

Currently, that translates roughly to:

  • Firefox 63+
  • Chrome 54+
  • Edge 79+
  • Safari 10.1+
  • Opera 41+

Debugging

If you are using VS Code, simply use the "launch" target. It will build the gateway in debugger mode.

If you are not using VS Code, run npm run debug and it will build the gateway and launch it with --inspect.

Testing

Install Additional Dependencies

In order to run the browser tests, you'll need to install Google Chrome and a JDK (e.g. OpenJDK).

Running Tests

To run the linter and all tests:

$ npm run test

To run a single test:

$ npm run jest build/test/{test-name}.js

Source Code Structure

  • config/ - Gateway configuration files
  • deb/ - Tools for building .deb packages
  • docker/ and Dockerfile - Tools for building Docker image
  • image/ - Tools for building the Raspberry Pi image
  • rpm/ - Tools for building .rpm packages
  • src/
    • addons-test/ - Add-ons used strictly for testing
    • controllers/ - App URL routes and their logic
    • iso-639/ - Small utility for interacting with ISO-639 data, i.e. locale names
    • models/ - Data model and business logic
    • platforms/ - Platform-specific functionality
    • plugin/ - Utility classes and methods used by add-ons
    • rules-engine/ - The rules engine
    • test/ - Integration and unit tests
    • views/ - Handlebars templates
    • addon-loader.ts - Script used for starting up Node-based add-ons
    • addon-manager.ts - Manages add-ons (e.g. Zigbee, Z-Wave)
    • addon-utils.ts - Utilities for add-ons, e.g. for reading the manifests
    • app.ts - The main back end
    • certificate-manager.ts - Certificate registration and renewal, via Let's Encrypt
    • constants.ts - System-wide constants
    • db.ts - Manages the SQLite3 database
    • deferred.ts - Wraps up a promise in a slightly more convenient manner for passing around, or saving
    • ec-crypto.ts - Elliptic curve helpers for the ES256 curve
    • errors.ts - Common error classes
    • jwt-middleware.ts - Express middleware for determining authentication status
    • log-timestamps.ts - Utilities for adding timestamps to console logging functions
    • migrate.ts - User profile migration
    • oauth-types.ts - OAuth types
    • passwords.ts - Password utilities
    • platform.ts - Platform-specific utilities
    • push-service.ts - Push notification service
    • router.ts - Routes app URLs to controllers
    • sleep.ts - Small utility to implement a promise-based sleep
    • tunnel-service.ts - Utilities to determine state of tunnel and manage the PageKite process
    • user-profile.ts - Manages persistent user data
    • utils.ts - Various utility functions
    • wifi-setup.ts - Initial Wi-Fi setup code for Raspberry Pi OS
  • static/ - Static CSS, JavaScript & image resources for web app front end
  • tools/ - Helpful utilities (not part of the build)
  • package.json - npm module manifest

More Repositories

1

wiki

Developer Wiki
Shell
291
star
2

webthing-node

Node.js implementation of a Web Thing server
TypeScript
232
star
3

webthing-rust

Rust implementation of a Web Thing server
Rust
206
star
4

webthing-arduino

Simple server for ESP8266, ESP32, Ethernet, or WiFi101-compatible boards compliant with Mozilla's proposed WoT API
C++
204
star
5

webthing-python

Python implementation of a Web Thing server
Python
177
star
6

api

Web Thing API Specification
HTML
164
star
7

registration_server

The registration server for WebThings Gateway.
Rust
78
star
8

addon-list

List of installable add-ons for WebThings Gateway
Python
77
star
9

gateway-docker

Legacy docker image for WebThings Gateway - now moved to main gateway repo at https://github.com/WebThingsIO/gateway
Dockerfile
71
star
10

webthing-java

Java implementation of a Web Thing server
Java
51
star
11

webthing-upy

MicroPython implementation of a Web Thing server
Python
50
star
12

zigbee-adapter

Zigbee adapter add-on for WebThings Gateway
JavaScript
46
star
13

example-adapter

Example adapter add-on for WebThings Gateway
JavaScript
34
star
14

homekit-adapter

HomeKit device adapter for WebThings Gateway
JavaScript
22
star
15

thing-url-adapter

Proxy adapter for Web Thing API endpoints
JavaScript
22
star
16

philips-hue-adapter

WebThings Gateway Philips Hue Adapter
TypeScript
21
star
17

mozilla-iot.github.io

Mozilla IoT Website
SCSS
20
star
18

curl-examples

Examples of using the gateway API using curl
Shell
19
star
19

gateway-addon-python

Python bindings for developing add-ons for WebThings Gateway
Python
16
star
20

zwave-adapter

Z-Wave adapter add-on for WebThings Gateway
JavaScript
15
star
21

tplink-adapter

TP-Link Kasa smart plug/bulb adapter for WebThings Gateway
Python
15
star
22

gateway-addon-node

Node bindings for developing add-ons for WebThings Gateway
TypeScript
13
star
23

virtual-things-adapter

WebThings Gateway Virtual Things Adapter for experimenting with new thing types
JavaScript
12
star
24

onvif-adapter

ONVIF Profile S video camera adapter
JavaScript
10
star
25

voice-addon

Voice control add-on for WebThings Gateway
JavaScript
8
star
26

yeelight-adapter

Yeelight device adapter for WebThings Gateway
JavaScript
7
star
27

weather-adapter

Weather adapter for WebThings Gateway
JavaScript
7
star
28

lg-tv-adapter

LG webOS TV adapter for WebThings Gateway
JavaScript
7
star
29

serial-adapter

WebThings Gateway adapter for talking to serial-mcu based software through a serial port.
JavaScript
7
star
30

deconz-api

Talk to Zigbee devices using ConBee dongle or RaspBee HAT, modelled after xbee-api
JavaScript
7
star
31

gateway-deb

Debian package for running WebThings Gateway
Shell
6
star
32

things-controller

Things Controller
Java
6
star
33

roku-adapter

Roku adapter
JavaScript
6
star
34

mozgateway-alexa-skill

Alexa Skill to interact with Mozilla WebThings Gateway
Python
6
star
35

rpi-image-builder

Builds gate files needed to create a Raspberry Pi image
Shell
6
star
36

intent-parser

Intent Parser for the Mozilla WebThings Gateway
Python
5
star
37

schemas

A Web of Things schema repository
HTML
5
star
38

zigbee-zdo

Module for parsing and building Zigbee ZDO frames for use with xbee-api or deconz-api
JavaScript
5
star
39

android-app

A Web of Things client for Android
Kotlin
5
star
40

gpio-adapter

GPIO adapter add-on for WebThings Gateway
JavaScript
5
star
41

gateway-addon-ipc-schema

JSON-Schema for add-on IPC messages
Python
5
star
42

meross-adapter

Meross smart device adapter for WebThings Gateway
Python
4
star
43

webthing-tester

Web Thing test script
Python
4
star
44

tapo-adapter

TP-Link Tapo smart plug adapter for WebThings Gateway
Python
4
star
45

tunnelclient-rs

A Rust client library for the DNS/pagekite tunnel
Rust
4
star
46

node-mozilla-iot-gateway

gateway package for OpenWRT
Makefile
3
star
47

serial-mcu

MCU side code which talks with the serial-adapter
C++
3
star
48

registration-server-docker

Docker image for WebThingsIO/registration_server
Dockerfile
3
star
49

twilio-adapter

Simple adapter exposing the texting part of the Twilio API to the WebThings Gateway
JavaScript
3
star
50

sengled-adapter

Sengled Wi-Fi smart bulb adapter for WebThings Gateway
Python
3
star
51

wake-on-lan-adapter

Wake-on-LAN adapter for WebThings gateway.
JavaScript
3
star
52

email-sender-adapter

Simple SMTP-based email sending adapter for the WebThings Gateway
JavaScript
3
star
53

crateway

Rust
3
star
54

gateway-package-turris-omnia

WebThings gateway package for theTurris Omnia
Makefile
2
star
55

le-store-certbot

Mozilla IoT's fork of le-store-certbot
JavaScript
2
star
56

device-compat

Hardware compatibility data for WebThings Gateway
JavaScript
2
star
57

cli

Command line tools for working with things
Python
2
star
58

wot-adapter

Proxy adapter for W3C compliant WoT devices
TypeScript
2
star
59

gateway-ipc-types-rust

Rust
2
star
60

pulse-adapter

Adapter which can create pulse devices.
JavaScript
2
star
61

le-challenge-dns

Mozilla's iot fork of le-challenge-dns to issue certificates automatically
JavaScript
2
star
62

example-extension

Example extension add-on for WebThings Gateway
JavaScript
2
star
63

http-on-off-wifi101

Simple HTTP server which turns an LED on or off
C++
2
star
64

gotify-notifier

Simple notifier which uses a self-hosted Gotify server.
JavaScript
2
star
65

things-browser

Things Browser
1
star
66

webthingsio.github.io

HTML
1
star
67

webhook-events

JavaScript
1
star
68

scene-control-adapter

WebThings Gateway add-on to emulate scenes
JavaScript
1
star
69

earthquake-monitor-adapter

Earthquake monitor for WebThings Gateway
Python
1
star
70

tide-calendar-adapter

Tide calendar for WebThings Gateway
Python
1
star
71

mailchimp-proxy

Python
1
star
72

speed-test-adapter

Internet speed test adapter for WebThings Gateway
Python
1
star
73

gateway-package-docker

Docker images for creating the gateway .ipk files for OpenWRT
Dockerfile
1
star
74

example-notifier

Example notifier add-on for WebThings Gateway
JavaScript
1
star
75

eufy-adapter

Eufy smart plug/bulb adapter for WebThings Gateway
Python
1
star
76

etekcity-adapter

Etekcity smart plug/switch adapter for WebThings Gateway
Python
1
star
77

xctu-logdump

Parses an XCTU log file
JavaScript
1
star
78

gateway-aur

AUR package for running WebThings Gateway
Shell
1
star