Golang实现Viessmann Vitotrol网络服务客户端功能的插件库go-vitotrol的使用

概述

go-vitotrol是一个提供访问Viessmann™ Vitotrol™云API的Golang库，用于控制和监控锅炉设备。

安装

vitotrol命令行工具

要获取vitotrol可执行文件：

Go 1.18及以上版本

go install github.com/maxatome/go-vitotrol/cmd/vitotrol@master

Go 1.18之前版本

go get -u github.com/maxatome/go-vitotrol/cmd/vitotrol

库安装

go get -u github.com/maxatome/go-vitotrol

注意：从Go 1.18开始，-u参数变得无用。

功能

当前实现了以下API请求：

• 登录(Login)
• 获取设备列表(GetDevices)
• 请求刷新状态(RequestRefreshStatus)
• 请求写入状态(RequestWriteStatus)
• 获取数据(GetData)
• 写入数据(WriteData)
• 刷新数据(RefreshData)
• 获取错误历史(GetErrorHistory)
• 获取时间表(GetTimesheet)
• 写入时间表数据(WriteTimesheetData)
• 获取类型信息(GetTypeInfo)

使用示例

命令行工具使用

usage: vitotrol [OPTIONS] ACTION [PARAMS]
  -config string
        login+password config file
  -debug
        print debug information
  -device string
        DeviceID, index, DeviceName, DeviceId@LocationID, DeviceName@LocationName (see `devices' action) (default "0")
  -json
        used by `timesheet' action to display timesheets using JSON format
  -login string
        login on vitotrol API
  -password string
        password on vitotrol API
  -verbose
        print verbose information

ACTION & PARAMS can be:
- devices              list all available devices
- list [attrs|timesheets]  list attribute (default) or timesheet names
- get ATTR_NAME ...    get the value of attributes ATTR_NAME, ... on vitodata
                         server
- get all              get all known attributes on vitodata server
- rget ATTR_NAME ...   refresh then get the value of attributes ATTR_NAME, ...
                         on vitodata server
- rget all             refresh than get all known attributes on vitodata server
- bget ATTR_IDX ...    get the value of attributes ATTR_IDX, ... on vitodata
                         server without checking their validity before (for
                         developing purpose)
- rbget ATTR_IDX ...   refresh then get the value of attributes ATTR_IDX, ...
                         on vitodata server without checking their validity
                         before (for developing purpose)
- set ATTR_NAME VALUE  set the value of attribute ATTR_NAME to VALUE
- timesheet TIMESHEET ...
                       get the timesheet TIMESHEET data
- set_timesheet TIMESHEET '{"wday":[{"from":630,"to":2200},...],...}'
                       replace the whole timesheet TIMESHEET
                       wday is either a day (eg. mon) or a range of days
                       (eg. mon-wed or sat-mon)
                       The JSON content can be in a file with the syntax @file
- errors               get the error history
- remote_attrs         list server available attributes
                         (for developing purpose)

配置文件

默认配置文件位于$HOME/.vitotrol-api，格式如下：

LOGIN
PASSWORD

代码示例

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/maxatome/go-vitotrol"
)

func main() {
	// 创建客户端
	client := vitotrol.NewClient(nil)

	// 从环境变量获取凭证
	login := os.Getenv("VITOTROL_LOGIN")
	password := os.Getenv("VITOTROL_PASSWORD")

	// 登录
	err := client.Auth(login, password)
	if err != nil {
		log.Fatalf("登录失败: %v", err)
	}

	// 获取设备列表
	devices, err := client.GetDevices()
	if err != nil {
		log.Fatalf("获取设备列表失败: %v", err)
	}

	// 打印设备信息
	for i, dev := range devices {
		fmt.Printf("设备 %d: %+v\n", i, dev)
	}

	// 选择第一个设备
	if len(devices) == 0 {
		log.Fatal("没有找到设备")
	}
	device := devices[0]

	// 获取设备属性
	attrs, err := client.GetData(device, nil)
	if err != nil {
		log.Fatalf("获取属性失败: %v", err)
	}

	// 打印属性
	for _, attr := range attrs {
		fmt.Printf("%s: %v (%s)\n", attr.Name, attr.Value, attr.Unit)
	}
}

许可证

go-vitotrol采用MIT许可证发布。

其他

想要自动将属性值导入Influx数据库？可以参考vitotrol2influx。