bindings

Bindings

Bindings are the YAHAS equivalent of drivers. They are used by items to send data to and receive data from “the outside”, ie. soft- or hardware that is not part of YAHAS itself.

Loading Bindings

YAHAS Core automatically loads the correct binding when it is requested by an item for the first time. The binding needs to be located in bindings in binary format (.so)

Configuration

In general bindings have 2 palces where they can be configured:

binding field in the item in items.json global configuration file in config/bindings

Available Bindings

MQTT

The MQTT Binding can be used to connect YAHAS to a MQTT broker such as mosquitto. You can use 1 or 2 topics per item. 2 topics are useful for publishing (sending) to one topic, but subscribing (receiving) from another. For example, the Tasmota Firmware for the popular Sonoff modules has a command and a state topic.

Global Configuration The global configuration file is in config/bindings/mqtt.json. It is used to specify the MQTT broker and define a user id

{
    "client-id": "yahas",
    "server": "<broker>:1883"
}

simply replace with the IP address or hostname of your MQTT broker and change client-id with your client id (normally you can also leave this one as is)

Item Configuration To use the MQTT Binding for an item, specify

{
rest of item config, like name, label, ...
    "binding":
    {
        "name": "mqtt",
        "settings": {
            "topic": "<topic>"
        }
    }
}  

Simply replace with the MQTT topic for your item.

dummy

The dummy plugin exists only for development/testing purposes and is of no use in normal use.

Developing Custom Bindings

YAHAS Bindings make use of the GO plugin architecture. To create a new plugin, you need to implement the binding interface defined in item/bindings.go

type binding interface {
    Init(*logging.Logger, *os.File) error
    RegisterItem(string, map[string]string) (*chan string, *chan string, error)
    SetConfig(string, map[string]string) error
    GetConfig(string) map[string]string
}

Secondly there needs to be an Instance of a data structure implementing the binding interface called Binding. Note that only the name of the variable is important, not the name of the type. The YAHAS core will look for this variable when loading the Binding.

Init

The init function is called once the Binding is loaded and should initialise the Binding. Every Binding gets their own logger to log to the system log. This logger should be used with the appropriate level in favor of fmt.

The second argumaent is a file handle to the configuration file. While the Binding has direct access to this file and hence could use any format it should use JSON for consistency.

func (myBinding*) Init(*logging.Logger, *os.File) error {
    return nil
}

If the binding cannot be initialised and should not be used an error can be returned to the core.

RegisterItem

RegisterItem is called for every item that specifies that binding in its configuration. The core provides the name of the item to be registered as well as a map of the parameters specified in the item’s binding object. It needs to return a send and a receive channel as well as an error if anythin went wrong.

The send channel is used by the core to send updates to an item, so your binding needs to receive from that channel (core -> binding). The receive channel goes the opposite direction, meaning it is used in your binding to send updates to the core (core <- binding).