README

🏛️ Bibliotek 📚 Build Status GitHub release go.dev reference

Bibliotek ('library' in Swedish) provides common primitives and utilities for integrating with and extending the Hemtjänst platform.

Usage

client client godoc

The client package should be used if what you want to do is publish/control your own devices but do not care about other devices in the system.

For example, lets say you want to control devices connected to a Z-Wave network, or republish external datasources like an HTTP API as a device (e.g a temperature sensor).

server server godoc

The server package allows you to fetch all devices, their updates and send them commands. It does not allow for the creation of devices.

It can be used to implement things like a HomeKit bridge or to watch for and republish device data, like sensor readings, to another platform (e.g Prometheus).

Take a look at cmd/explorer on how to use it.

transport/mqtt mqtt transport godoc

The transport/mqtt package contains everything needed to transport device data over MQTT. It also contains the Flags() and MustFlags() helpers that provide a set of flags to configure common MQTT options.

Contributing

Contributions are very welcome. Do ensure you run the tests:

$ go test -race -v -coverprofile=profile.cov $(go list ./...)
...

Note that in CI the _integration_test.go will run too. You can run them locally as well by setting BIBLIOTEK_TEST_INTEGRATION=1.

In order for these test to complete successfully you'll have to spin up an MQTT broker and if the MQTT broker is not found on localhost:1883 specify a host:port string in the MQTT_ADDRESS environment variable.

$ env BIBLIOTEK_TEST_INTEGRATION=1 go test -race -v -coverprofile=profile.cov $(go list ./...)
...
Expand ▾ Collapse ▴

Documentation

Overview

Package bibliotek is a library for the Hemtjänst ecosystem.

It comes with a few different packages, most importantly client, server and transport.

Client

The client package lets you create new devices and register them onto MQTT, so that other things can become aware of it. For example, if you wanted to take devices from an IoT gateway like the IKEA Tradfri gateway and make them available as Hemtjänst devices, this is where you'd start.

Server

The server package lets you observe all existing devices, subscribe to state changes as well as change the state of existing devices. This is useful if you want to create a bridge to somewhere else. A HomeKit bridge could be implemented with it, or exposing device information through another medium, like providing an HTTP API.

Transport

The transport package contains some MQTT related utilities. You'll likely never need them, aside from transport/mqtt.Flags() so you don't have to define all the different flags for setting up a connection to an MQTT broker for ya CLI utility yourself.

Source Files

View all

Directories

Path Synopsis
Package client lets your create and announce devices on the MQTT broker.
 Package client lets your create and announce devices on the MQTT broker.
cmd
demo
demo creates a bunch of fake devices defined in a config file in order to demo the hemtjänst system.
 demo creates a bunch of fake devices defined in a config file in order to demo the hemtjänst system.
explorer
Package device defines the basic requirements of a device
 Package device defines the basic requirements of a device
Package feature defines the basic requirements of a feature
 Package feature defines the basic requirements of a feature
Package server lets you interact with existing devices
 Package server lets you interact with existing devices
Package transport encapsulates the logic of how devices and features can be transported over a specific protocol
 Package transport encapsulates the logic of how devices and features can be transported over a specific protocol
mqtt
Package mqtt defines how devices map onto an MQTT transport.
 Package mqtt defines how devices map onto an MQTT transport.