History

Joshua Rich 39480b1f64 docs: 📝 update build documentation		2024-04-28 08:48:58 +10:00
..
README.md	docs: 📝 update build documentation	2024-04-28 08:48:58 +10:00
agent.md	docs: 🐛 remove old method from interface example	2024-02-22 10:05:13 +10:00
sensors.md	docs: 📝 update developer agent docs	2024-02-22 10:03:41 +10:00

README.md

Go Hass Agent Development Notes

Build Requirements

In addition to a Go installation, Go Hass Agent needs a few other Go tools installed:

# nfpm is used to create linux distro packages
go install github.com/goreleaser/nfpm/v2/cmd/nfpm@latest
# fyne-cross is used build for older linux distributions
go install github.com/fyne-io/fyne-cross@latest
# stringer auto-generates some String() methods
go install golang.org/x/tools/cmd/stringer@latest
# gotext is used for translations
go install golang.org/x/text/cmd/gotext@latest
# moq is used for unit tests
go install github.com/matryer/moq@latest

The Fyne UI toolkit that is used by Go Hass Agent also requires some development libraries installed. See the Fyne prerequisites documentation for what you need to install.

Development Environment

It is recommended to use Visual Studio Code. This project makes use of a Devcontainer to provide some convenience during development.

If using Visual Studio Code, you should be prompted when opening your cloned copy of the code to set up the dev container. The container contains an installation of Home Assistant and Mosquitto (MQTT broker) that can be used for testing. They should be started automatically.

Home Assistant will be listening on http://localhost:8123.
Mosquitto will be listening on http://localhost:1833.

Note that while you can also build and run the agent within the container environment, this will limit what sensors are reported and may even hinder development of new sensors. As such, it is recommended to build and run outside the container. You can still connect to Home Assistant running within the container, as it is exposed as per above.

Building

Go Hass Agent makes use of go generate to generate some of the code. A typical build process would be:

source build/env.amd64
go generate ./...
go build

Packages

Go Hass Agent uses nfpm to create packages for Fedora, Arch, and Ubuntu and fyne-cross to create packages for Debian and Linux distributions with older libraries.

To build packages:

source build/env.amd64
nfpm package --config .nfpm.yaml --packager rpm --target dist
nfpm package --config .nfpm.yaml --packager deb --target dist
nfpm package --config .nfpm.yaml --packager archlinux --target dist

Packages will be available under the dist/ folder.

To build a package for Debian with fyne-cross:

source build/env.amd64
fyne-cross linux -arch=${PKG_ARCH} -name go-hass-agent -icon assets/trayicon/logo-pretty.png -release

The .tar.xz will be available under fyne-cross/dist/linux-${PKG_ARCH}/.

Other Architectures

Go Hass Agent can also be built for arm and arm64 with cross-compilation. This is only supported on Ubuntu as the host for cross-compiles. To build for a different architecture, replace the source build/env.amd64 in the above snippets with one of the following:

source build/env.arm # for arm
source build/env.arm64 # for arm64

You will need to have the appropriate cross-compiler and libraries installed first. See the .github/workflows/build.yml file for how to configure and install dependencies for cross-compilation on Ubuntu.

[!NOTE] The devcontainer has all the necessary compilers and libraries installed for cross-compilation.

Container Images

A Dockerfile that you can use to build an image can be found here.

You can build an image with a command like the following (using Podman):

podman build --file ./Dockerfile --network host --tag go-hass-agent

Committing Code

This repository is using conventional commit messages. This provides the ability to automatically include relevant notes in the changelog. The TL;DR is when writing commit messages, add a prefix:

feat: for a new feature, like a new sensor.
fix: when fixing an issue.
refactor: when making non-visible but useful code changes.
…and so on. See the link above or see the existing commit messages for examples.

Extending the Agent

Adding OS support

The intention of the agent design is to make it OS-agnostic.

Most OS specific code for fetching sensor data should likely be part of a GOARCH package and using filename suffixes such as filename_GOOS_GOARCH.go. See the files under linux/ as examples.

For some OSes, you might need some code to initialise or create some data source or API that the individual sensor fetching code uses. This code should be placed in device/, using filename suffixes such as filename_GOOS_GOARCH.go

For example, on Linux, a D-Bus connection is used for a lot of the sensor data gathering.

In such cases, you should pass this through as a value in a context. You can create the following function for your platform:

SetupContext(ctx context.Context) context.Context

It should accept a context.Context and derive its own context from this base that contains the necessary values for the platform. It will be propagated throughout the code wherever a context is passed and available for retrieval and use.

An example can be found in device/device_linux.go.