Skip to content

Latest commit

 

History

History
134 lines (91 loc) · 3.48 KB

README.md

File metadata and controls

134 lines (91 loc) · 3.48 KB
Raw

WireGuard implementation for ESPHome

This is an implementation of WireGuard® VPN for ESPHome, based on Wireguard Implementation for ESP-IDF (by @trombik).

The branch trombik/main will be kept in sync with @trombik's main branch.

The branch main is where I push my most "stable" code.

PlatformIO Registry

Status

The code is alpha.

A single tunnel to a WireGuard peer has been working.

Supported boards and frameworks

The code works only on esp32 boards with both frameworks: esp-idf and Arduino.

The original @trombik's code was designed for esp-idf only but it seems to work on Arduino too.

Usage

Add the following configuration to your ESPHome yaml file:

# Define wireguard external source
external_components:
  - source:
      type: git
      url: https://github.com/droscy/esphome
      ref: wireguard/main
    components:
      - wireguard
      - wireguard_status
      - wireguard_handshake

# Setup a time source.
# Do not use 'homeassistant' platform if Home Assistant is on the remote
# peer because the time synchronization is a prerequisite to establish
# the vpn link.
time:
  - platform: sntp

# Setup WireGuard
wireguard:
  address: x.y.z.w
  private_key: private_key=
  peer_endpoint: wg.server.example
  peer_public_key: public_key=

  # optional netmask (this is the default if omitted)
  netmask: 255.255.255.255

  # optional custom port (this is the wireguard default)
  peer_port: 51820

  # optional pre-shared key
  peer_preshared_key: shared_key=

  # optional keepalive in seconds (disabled by default)
  peer_persistent_keepalive: 25

  # optional list of allowed ip/mask (the default is to allow any host if omitted)
  peer_allowed_ips:
    - x.y.z.0/24
    - l.m.n.o/32  # the /32 can be omitted for single host
    - [...]

  # reboot the board if remote peer in unreachable (default to 15min, set to 0s to disable)
  reboot_timeout: 15min

Sensors

The wireguard_status binary sensor can be used to check if remote peer is online:

binary_sensor:
  - platform: wireguard_status
    name: 'WireGuard Status'

    # optional (default to 10s)
    update_interval: 10s

The wireguard_handshake sensor can be used to track the timestamp of the latest completed handshake:

sensor:
  - platform: wireguard_handshake
    name: 'WireGuard Latest Handshake'

    # optional (default to 60s)
    update_interval: 60s

References

For additional information see:

License

BSD 3-Clause License (SPDX ID: BSD-3-Clause).

Except where explicitly written in files themselves or when other license files state differently.

Authors