indoorclimate

README

HomeDashboard Indoor Climate DataSource

Fetches indoor climate data from Bluetooth sensor devices, e.g. Xiaomi Mi Temperature and Humidity Monitor 2, and publishes this data to specified targets. Indooe climate data can be collected in two ways.

• Running on a M5Stack Core2, using ESP32 Wifi and Bluetooth
• Running on a host with Bluetooth device, e.g. a Raspberry PI

M5Stack

IndoorClimate provides a sketch which can be uploaded to a M5Stack Core2. With a few adjustements, e.g. skip LCD updates, this sketch can be uploaded to a lot of other ESP32 boards.

Config

You have to add AWS IOT settings at settings.h and necessary certificates to certs.h. For WiFi connections add you SSID and password to wifi_credentials.h.

AWS IOT Setup

To setup AWS IOT device, certificate, policy and rule have a look at AWS IOT Setup. A lambda function to process IOT events is available at lambda.

Sensor Data Collector

Collector can be compiled to a binary and executed as a deamon.

Define Devices and Characteristics

You've to add a list of devices and characteristics you want to observe in config.

indoorclimate:
  schedule: 10m
  devices:
    - id: "A4:XX:XX:XX:26:41"
  characteristics:
    - uuid: "00002a6e-0000-1000-8000-00805f9b34fb"
      type: "temperature"
    - uuid: "00002a6f-0000-1000-8000-00805f9b34fb"
      type: "humidity"
    - uuid: "00002a19-0000-1000-8000-00805f9b34fb"
      type: "battery"

Schedule

This value defines how often sensor data should be read. See Config for more details about supported values.

Devices

Provide a list of MAC addesses for Bluetooth environment sensors.

Characteristics

Define a list of observed characteristics by their UUID and specifiy a indoor cliamte data type.

Targets

By default a SensorDataCollector doesn't have any target assigned. This means your indoor climate date get lost. Targets package provides different publishers you can assign to a SensorDataCollector to send indoor climate data to a target.

Usage

After creating a new collector you can call it's Run method to start consuming new indoor climate data from MQTT broker. By default all received indoor climate data are send to default target which is a logger, only. Collector will run until you cancel passed context.

    import (
      "fmt"
      "context"

       indoorclimate "github.com/tommzn/hdb-datasource-indoorclimate"  
       targets "github.com/tommzn/hdb-datasource-indoorclimate(targets"  
       config "github.com/tommzn/go-config"
	     log "github.com/tommzn/go-log"
    )
    
    conf, _ := config.NewConfigSource().Load()
    if err != nil {
        panic(err)
    }
    logger := log.NewLoggerFromConfig(conf, nil)

    datacollector := indoorclimate.NewSensorDataCollector(conf, logger)
    if err != nil {
        panic(err)
    }

    datacollector.AppendTarget(targets.NewStdoutTarget())
    if err := datacollector.Run(context.Background()); err != nil {
      fmt.Println)err  
    }
    

Links

• HomeDashboard Documentation

Documentation

Index

• type Characteristic
• type DevicePlugin
• type DevicePluginKey
• type IndoorClimateMeasurement
• type MeasurementType
• type MockPlugin
  • func NewMockPlugin(logger log.Logger, deviceId *string) *MockPlugin
  • func (plugin *MockPlugin) MessageHandler(client mqtt.Client, message mqtt.Message)
  • func (plugin *MockPlugin) SetMeasurementChannel(channel chan<- IndoorClimateMeasurement)
• type MockTarget
  • func NewMockTarget() *MockTarget
  • func (target *MockTarget) SendMeasurement(measurement IndoorClimateMeasurement) error
• type MqttCollector
  • func NewMqttCollector(conf config.Config, logger log.Logger) *MqttCollector
  • func (collector *MqttCollector) AppendSubscription(subscription MqttSubscriptionConfig)
  • func (collector *MqttCollector) AppendTarget(newTarget Publisher)
  • func (collector *MqttCollector) Run(ctx context.Context) error
• type MqttLivenessObserver
  • func NewMqttLivenessObserver(conf config.Config, logger log.Logger) *MqttLivenessObserver
  • func (observer *MqttLivenessObserver) MessageHandler(mclient mqtt.Client, msg mqtt.Message)
  • func (observer *MqttLivenessObserver) Run(ctx context.Context, wg *sync.WaitGroup) error
• type MqttSubscription
• type MqttSubscriptionConfig
• type Publisher

Types

type Characteristic

type Characteristic struct {
	// contains filtered or unexported fields
}

Characteristic is a songle sensor value.

type DevicePlugin

type DevicePlugin interface {
	MqttSubscription

	// SetMeasurementChannel assigns a channel plugin should write extracted indoor climate measurements to.
	SetMeasurementChannel(chan<- IndoorClimateMeasurement)
}

DevicePlugin is used to subscribe to MQTT topics and extract measurements from published data.

type DevicePluginKey

type DevicePluginKey string

DevicePluginKey defines a plugin for devices of a specific manufacturer.

const (
	PLUGIN_SHELLY DevicePluginKey = "shelly"
	PLUGIN_LOGGER DevicePluginKey = "logger"
)

type IndoorClimateMeasurement

type IndoorClimateMeasurement struct {
	DeviceId  string
	Timestamp time.Time
	Type      MeasurementType
	Value     string
}

IndoorClimateMeasurement is a metric read from a sensor device.

type MeasurementType

type MeasurementType string

MeasurementType is a indoor climate date type, e.g. temperature.

const (
	MEASUREMENTTYPE_TEMPERATURE MeasurementType = "temperature"
	MEASUREMENTTYPE_HUMIDITY    MeasurementType = "humidity"
	MEASUREMENTTYPE_BATTERY     MeasurementType = "battery"
)

type MockPlugin

type MockPlugin struct {
	// contains filtered or unexported fields
}

MockPlugin can be used for testing. it generates static indoor climate measuremnts based on received message.

Message		|	Indoor CLimate Data

--------------------------------------

temperature	|	Temperature 24.7°C
humidity	|	Humidity 53.9%
battery		|	Capacity 87%
<default>	|	Temperature 12.3°C

func NewMockPlugin

func NewMockPlugin(logger log.Logger, deviceId *string) *MockPlugin

NewMockPlugin creates a new mock plugin.

func (*MockPlugin) MessageHandler

func (plugin *MockPlugin) MessageHandler(client mqtt.Client, message mqtt.Message)

MessageHandler process message received from MQTT topic and pulishes static indoor climate data depending on message payload.

func (*MockPlugin) SetMeasurementChannel

func (plugin *MockPlugin) SetMeasurementChannel(channel chan<- IndoorClimateMeasurement)

SetMeasurementChannel assign a channel measuremnts should be written to.

type MockTarget

type MockTarget struct {
	Measurements []IndoorClimateMeasurement
}

MockTarget can be used for testing. It appends all measurements to an internal slice.

func NewMockTarget

func NewMockTarget() *MockTarget

func (*MockTarget) SendMeasurement

func (target *MockTarget) SendMeasurement(measurement IndoorClimateMeasurement) error

type MqttCollector

type MqttCollector struct {
	// contains filtered or unexported fields
}

MqttCollector subcribes to MQTT topics to extract indoor climate date from published messages.

func NewMqttCollector

func NewMqttCollector(conf config.Config, logger log.Logger) *MqttCollector

NewMqttCollector returns a new collector listen for MQTT messages to obtain indoor climate data.

func (*MqttCollector) AppendSubscription

func (collector *MqttCollector) AppendSubscription(subscription MqttSubscriptionConfig)

AppendSubscription will append passed subscription to internal subscription list.

func (*MqttCollector) AppendTarget

func (collector *MqttCollector) AppendTarget(newTarget Publisher)

AooendTarget will append passed target to internal publisher list.

func (*MqttCollector) Run

func (collector *MqttCollector) Run(ctx context.Context) error

Run start indoor climate collector. It's an infinite loop until given context is canceled.

type MqttLivenessObserver

type MqttLivenessObserver struct {
	// contains filtered or unexported fields
}

MqttLivenessObserver can be use to observer a MQTT server.

func NewMqttLivenessObserver

func NewMqttLivenessObserver(conf config.Config, logger log.Logger) *MqttLivenessObserver

NewMqttLivenessObserver creates a new liveness probe for MQTT.

func (*MqttLivenessObserver) MessageHandler

func (observer *MqttLivenessObserver) MessageHandler(mclient mqtt.Client, msg mqtt.Message)

MessageHandler listen for message on liveness topic and writes them to internal prove chan.

func (*MqttLivenessObserver) Run

func (observer *MqttLivenessObserver) Run(ctx context.Context, wg *sync.WaitGroup) error

Run liveness prove on given schedule.

type MqttSubscription

type MqttSubscription interface {

	// MessageHandler process received data received from a mqtt topic
	MessageHandler(mqtt.Client, mqtt.Message)
}

MqttSubscription is used to handle messages received from subscribes MQTT topics.

type MqttSubscriptionConfig

type MqttSubscriptionConfig struct {
	Topic  string
	Plugin DevicePlugin
}

MqttSubscriptionConfig define a MQTT topic and it's message handler plugin.

type Publisher

type Publisher interface {

	// SendMeasurement will start to transfer passed measurement to a target.
	SendMeasurement(IndoorClimateMeasurement) error
}

Publisher sends given measuremnts to different targets.