hub

README

Your Private, Decentralized IoT Device Hub

Securely access your devices from anywhere on the Internet · No app required

Report Bug · Request Feature · Join Our Slack · Twitter

Features

• Privacy first: no user data collected or stored; no cookies; no tracking; no ads
• Decentralized: your hub is independent from your neighbor's; there is no central control over any hub
• Secure: TLS-secure communication from device and hub, and from hub to browser
• Device targets: target popular SBCs and microcontrollers such as Raspberry Pi and Arduino
• No app to install: runs as a responsive, single page web application; all you need is a browser
• Containerized: runs in a docker container; no dependencies to install
• Small footprint: minimum hardware specification is 0.1 vCPU, 256MB of RAM and 10GB of disk space.
• 100% Open Source: written in Go and TinyGo (and some html/css/javascript for the UI)

Quick Start

Free on Koyeb

Click the button to install Merliot Hub on the Koyeb cloud (a Koyeb account is required).

Review the settings and click Apply. It takes a few minutes for the hub to start. Browse to https://APP.koyeb.app/ to view hub and deploy devices.

Docker

docker pull merliot/hub
docker run -p 80:8000 merliot/hub

Browse to http://<host> to view hub and deploy devices, where <host> is your IP address or hostname of your computer.

• Install
  • Local Install
  • Cloud Install
  • Local and Cloud Install
  • Install from Source
• Devices
  • Saving Devices
  • Supported Targets
  • Example Devices
  • Making a New Device
• Environment Variables

Install

Install Merliot Hub locally on your computer, on the cloud, or both, using our Docker image, without having to install all the dependencies. (If you don't have Docker, you can install the hub from source).

Local Install

Install Merliot Hub on a computer on your local network. The devices will dial into the hub on your local network. You access the hub at it's local IP address.

[!NOTE] Prerequisite: Installed Docker environment.

docker pull ghcr.io/merliot/hub
docker run -p 8000:8000 merliot/hub

Browse to http://<host>:8000 to view hub and deploy devices, where <host> is your IP address or hostname of your computer.

You can pass in environment variables. For example, to set the Wifi SSID/Passphrase to be programmed into the devices:

docker run -e WIFI_SSIDS="My SSID" -e WIFI_PASSPHRASES="mypassphrase" -p 8000:8000 merliot/hub

Or to protect your hub with a user/password:

docker run -e USER="xxx" -e PASSWD="yyy" -p 8000:8000 merliot/hub

Cloud Install

You can install Merliot Hub on the Internet using a cloud providers such as Koyeb, Digital Ocean, and GCP (Google Cloud Platform), to name a few. The docker image path is:

docker pull ghcr.io/merliot/hub

Environment Variables

PORT=8000. The hub listens on port :8000.

WS_SCHEME=wss://. This uses the secure websocket scheme to connect to the hub.

(See additional environment variables).

Install on Koyeb for Free

Click the button to install Merliot Hub on Koyeb, for Free! A Koyeb account is required.

All cloud providers require an account, there's no getting around that. Some have free-tiers or introductory credits to get started. Koyeb offers a free virtual machine with more than enough resources to run a hub.

Review the settings for the virtual machine (VM) and click Apply. It takes a few minutes for the VM to start. Your new hub will have an Internet URL in the format:

https://hub-ACCOUNT.koyeb.app/

Where ACCOUNT is your Koyeb account name.

[!TIP] If you own a domain name, you can map it to the hub URL.

Local and Cloud Install

Install Merliot Hub on a local computer and on the cloud, and the devices will dial into both.

On one hub, call it primary, set BACKUP environment to the URL of a backup hub. Do the oposite, setting BACKUP on backup to point to primary's URL. This way, regardless of which hub a device is created on, the device will dial into both hubs.

Install from Source

[!NOTE] Prerequisites:

• Go version 1.22 or higher
• TinyGo version 0.31.1 or higher.

git clone https://github.com/merliot/hub.git
cd hub
go run ./cmd

Browse to http://<host> to view hub and deploy devices, where <host> is your IP address or hostname of your computer.

You can pass in environment variables. For example, to set the user/passwd:

USER=foo PASSWD=bar go run ./cmd`

Devices

A device is a gadget you build. The picture-equation for a device is:

A device comprises a platform, some I/O, and the software (firmware) that runs on the device. In this picture, the Raspberry Pi is the platform, the I/O is the relay and flow meter. The device control code is written in Go; the device view code is written in HTML/JS/CSS.

The device dials into the hub so you can monitor and control the device from the hub. Multiple devices, of different types, can dial into the hub.

The device is also a local web server, so you can browse directly to the device's address, skipping the hub.

Saving Devices

Supported Targets

Merliot Hub supports devices created on these platforms:

• Raspberry Pi 3/4/5/Zero W/Zero 2 W
• Arduino Nano Connect rp2040
• Seeed Wio Terminal
• Adafruit PyPortal

Example Devices

• Skeleton Device (template for new devices)
• Device Hub (a hub is a device also)
• Relay Controller
• Garage Door Opener
• MorningStar ProStar Solar Charge Controller (Modbus)

Making a New Device

Environment Variables

These variables configure the hub and devices:

BACKUP

By default, the each device will dial into the hub that created the device. To also dial into a backup hub, set BACKUP to the backup hub's address.

For example, a primary hub is at local address http://192.168.1.10. Any device created on the primary hub will dial into the primary hub's address. A backup hub is at cloud address https://hub.merliot.net. Set BACKUP=https://hub.merliot.net on the primary hub. Now the devices created on the primary hub will dial into both hubs.

[!TIP] You can additionally set BACKUP=http://192.168.1.10 on the backup hub, so regardless of which hub creates the device, the device will dial into both hubs.

[!IMPORTANT] The backup hub must have the same USER/PASSWD and WIFI settings as the primary hub.

DEMO

Run hub in demo mode, default is false. Implies LOCKED, if set true.

DEVICES

Hub devices. This is a JSON-formatted list of devices. The format is:

{
	"<id>": {
		"Model": "<model>",
		"Name": "<name>",
		"DeployParams": "<deploy params>"
	},
}

Example with two devices:

{
	"6bb645c9-db12e9c9": {
		"Model": "skeleton",
		"Name": "example",
		"DeployParams": "target=demo\u0026gpio-default=on"
	},
	"6bccaffd-6d8fab72": {
		"Model": "garage",
		"Name": "garage",
		"DeployParams": "target=demo\u0026door=garage+door\u0026relay=DEMO0"
	},
}

LOCKED

Lock the hub making it read-only, default is false.

PORT

Port the hub listens on, default is PORT=8000.

USER, PASSWD

Set user and password for HTTP Basic Authentication on the hub. The user will be prompted for user/password when browsing to the hub. These values (if set) are automatically passed down to the device when deployed, and the device connects to the hub using these creditials. For example:

• USER=foo
• PASSWD=bar

WIFI_SSIDS, WIFI_PASSPHRASES

Set Wifi SSID(s) and passphrase(s) for Wifi-enabled devices built with TinyGo. These are matched comma-delimited lists. For each SSID, there should be a matching passphrase. For example:

• WIFI_SSIDS="test,backup"
• PASSPHRASES="testtest,backdown"

So testtest goes with SSID test, and backdown goes with SSID backup.

WS_SCHEME

Websocket scheme to use for dialing back into the hub. Default is WS_SCHEME=ws://. If the hub is running under https://, then set WS_SCHEME=wss://.

Hub Memory and CPU Requirements

The hub consumes little memory (or CPU) and can run on a Linux machine (or virtual machine) with a minimum of 256M and 2G disk space.

Documentation

Index

• func New(id, model, name string) dean.Thinger
• type Child
• type Children
• type Hub
  • func (h *Hub) GenerateUf2s(dir string) error
  • func (h *Hub) LoadDevices(devices string)
  • func (h *Hub) RegisterModel(model string, maker dean.ThingMaker)
  • func (h *Hub) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (h *Hub) SetBackup(backup string)
  • func (h *Hub) SetDemo(demo bool)
  • func (h *Hub) SetServer(server *dean.Server)
  • func (h *Hub) Subscribers() dean.Subscribers

Functions

func New

func New(id, model, name string) dean.Thinger

Types

type Child

type Child struct {
	Model          string
	Name           string
	DeployParams   string `json:"DeployParams,omitempty"`
	Online         bool   `json:"-"`
	device.Devicer `json:"-"`
}

type Children

type Children map[string]*Child // keyed by id

type Hub

type Hub struct {
	*device.Device
	Version       string
	Demo          bool
	models.Models `json:"-"`
	Children
	// contains filtered or unexported fields
}

func (*Hub) GenerateUf2s

func (h *Hub) GenerateUf2s(dir string) error

func (*Hub) LoadDevices

func (h *Hub) LoadDevices(devices string)

func (*Hub) RegisterModel

func (h *Hub) RegisterModel(model string, maker dean.ThingMaker)

func (*Hub) ServeHTTP

func (h *Hub) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*Hub) SetBackup

func (h *Hub) SetBackup(backup string)

func (*Hub) SetDemo

func (h *Hub) SetDemo(demo bool)

func (*Hub) SetServer

func (h *Hub) SetServer(server *dean.Server)

func (*Hub) Subscribers

func (h *Hub) Subscribers() dean.Subscribers