diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 93068b1b5..d1fad8b4e 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -123,6 +123,7 @@ jobs: contents: write packages: write runs-on: ubuntu-20.04 + # NOTE: Ubuntu does not provide a container for armv6, so we can't build for that :( strategy: matrix: platform: diff --git a/README.md b/README.md index b9a98ea99..0ec52ac80 100644 --- a/README.md +++ b/README.md @@ -52,25 +52,25 @@ ## :notebook_with_decorative_cover: Table of Contents - [:notebook\_with\_decorative\_cover: Table of Contents](#notebook_with_decorative_cover-table-of-contents) -- [:star2: About the Project](#star2-about-the-project) - - [:dart: Features](#dart-features) +- [🌟 About the Project](#-about-the-project) + - [🎯 Features](#-features) - [📈 Sensors (by Operating System)](#-sensors-by-operating-system) - - [:penguin: Linux](#penguin-linux) - - [:robot: Script Sensors (All Platforms)](#robot-script-sensors-all-platforms) - - [:bus: Control via MQTT (All Platforms)](#bus-control-via-mqtt-all-platforms) + - [🐧 Linux](#-linux) + - [🤖 Script Sensors (All Platforms)](#-script-sensors-all-platforms) + - [🚌 Control via MQTT (All Platforms)](#-control-via-mqtt-all-platforms) - [🤔 Use-cases](#-use-cases) - [🗒️ Versioning](#️-versioning) -- [:toolbox: Getting Started](#toolbox-getting-started) +- [🧰 Getting Started](#-getting-started) - [🤝 Compatibility](#-compatibility) - - [:gear: Installation](#gear-installation) + - [🔽 Installation](#-installation) - [📦 Packages](#-packages) - [🚢 Container](#-container) -- [:eyes: Usage](#eyes-usage) +- [🕹️ Usage](#️-usage) - [🔛 First-run](#-first-run) - - [Running “Headless”](#running-headless) - - [Running in a container](#running-in-a-container) - - [Regular Usage](#regular-usage) - - [Configuration Location](#configuration-location) + - [👻 Running “Headless”](#-running-headless) + - [🐳 Running in a container](#-running-in-a-container) + - [♻️ Regular Usage](#️-regular-usage) + - [📌 Configuration Location](#-configuration-location) - [Script Sensors](#script-sensors) - [Requirements](#requirements) - [Supported Scripting Languages](#supported-scripting-languages) @@ -88,9 +88,16 @@ - [Custom D-BUS Controls](#custom-d-bus-controls) - [Other Custom Commands](#other-custom-commands) - [Security Implications](#security-implications-1) -- [:compass: Roadmap](#compass-roadmap) +- [⚙️ Building/Compiling Manually](#️-buildingcompiling-manually) + - [Build Requirements](#build-requirements) + - [Compiling](#compiling) + - [Cross Compilation](#cross-compilation) + - [Packages](#packages) + - [Container Images](#container-images) - [:wave: Contributing](#wave-contributing) - - [:scroll: Code of Conduct](#scroll-code-of-conduct) +- [💾 Committing Code](#-committing-code) + - [📜 Code of Conduct](#-code-of-conduct) +- [🧭 Roadmap](#-roadmap) - [:grey\_question: FAQ](#grey_question-faq) - [_Can I change the units of the sensor?_](#can-i-change-the-units-of-the-sensor) - [_Can I disable some sensors?_](#can-i-disable-some-sensors) @@ -99,14 +106,12 @@ - [_I've updated the agent and now I've got a bunch of duplicate/removed/disabled sensors?_](#ive-updated-the-agent-and-now-ive-got-a-bunch-of-duplicateremoveddisabled-sensors) - [_Can I reset the agent (start from new)?_](#can-i-reset-the-agent-start-from-new) - [_I want to run the agent on a server, as a service, without a GUI. Can I do this?_](#i-want-to-run-the-agent-on-a-server-as-a-service-without-a-gui-can-i-do-this) -- [:gem: Acknowledgements](#gem-acknowledgements) -- [:warning: License](#warning-license) +- [🤝 Acknowledgements](#-acknowledgements) +- [🧑‍⚖️ License](#️-license) - -## :star2: About the Project +## 🌟 About the Project - -### :dart: Features +### 🎯 Features #### 📈 Sensors (by Operating System) @@ -115,7 +120,7 @@ > report. In some cases, the **actual** sensors reported may be less due to > lack of support in the system configuration or missing hardware. -##### :penguin: Linux +##### 🐧 Linux - *Go Hass Agent Version*. Updated on agent start. - App Details: @@ -207,12 +212,12 @@ alarms. Updated ~every 1 minute. - Extracted from the `/sys/class/hwmon` file system. -#### :robot: Script Sensors (All Platforms) +#### 🤖 Script Sensors (All Platforms) All platforms can also utilise scripts to create custom sensors. See [scripts](#script-sensors). -#### :bus: Control via MQTT (All Platforms) +#### 🚌 Control via MQTT (All Platforms) Where Home Assistant is connected to MQTT, Go Hass Agent can add some controls for various system features. A selection of device controls are provided by @@ -253,8 +258,7 @@ number `MAJOR`.`MINOR`.`PATCH`, the gist of it is: [:arrow_up: Back to Top](#notebook_with_decorative_cover-table-of-contents) - -## :toolbox: Getting Started +## 🧰 Getting Started ### 🤝 Compatibility @@ -262,8 +266,7 @@ Currently, only Linux is supported. Though the code is designed to be extensible to other operating systems. See development information in the [docs](docs/README.md) for details on how to extend for other operating systems. - -### :gear: Installation +### 🔽 Installation #### 📦 Packages @@ -305,8 +308,7 @@ version over the latest container image, which might be unstable. [:arrow_up: Back to Top](#notebook_with_decorative_cover-table-of-contents) - -## :eyes: Usage +## 🕹️ Usage Go Hass Agent runs as a tray icon by default. It is operating system, distribution and desktop-environment agnostic and should manifest itself in any @@ -332,7 +334,7 @@ able to report sensors and receive notifications. When you have entered all the details, click **Submit** and the agent should start running and reporting sensors to the Home Assistant instance. -### Running “Headless” +### 👻 Running “Headless” Go Hass Agent will automatically detect if there is no GUI available and run in a “headless” mode with no UI. Registration will need to be completed manually as @@ -357,7 +359,7 @@ specifying the `--terminal` command-line option. If you want to run Go Hass Agent as a service on a headless machine, see the [FAQ](docs/faq.md#q-i-want-to-run-the-agent-on-a-server-as-a-service-without-a-gui-can-i-do-this). -### Running in a container +### 🐳 Running in a container There is rough support for running Go Hass Agent within a container. Pre-built images [are available](https://github.com/joshuar/go-hass-agent/pkgs/container/go-hass-agent). @@ -394,7 +396,7 @@ during registration. All the other volume mounts are optional, but functionality and the sensors reported will be severely limited without them. -### Regular Usage +### ♻️ Regular Usage When running, Go Hass Agent will appear as a device under the Mobile App integration in your Home Assistant instance. It should also report a list of @@ -403,7 +405,7 @@ parts of Home Assistant. [![Open your Home Assistant instance to the mobile_app integration.](https://my.home-assistant.io/badges/integration.svg)](https://my.home-assistant.io/redirect/integration/?domain=mobile_app) -### Configuration Location +### 📌 Configuration Location The configuration is located in a file called `preferences.toml` in `CONFIG_HOME/com.github.joshuar.go-hass-agent/` where `CONFIG_HOME` will @@ -429,7 +431,7 @@ run on its own schedule, specified using a Cron syntax. #### Requirements - Scripts need to be put in a `scripts` folder under the configuration directory - (see [Configuration Location](#configuration-location). + (see [Configuration Location](#configuration). - You can use symlinks, if supported by your Operating System. - Script files need to be executable by the user running Go Hass Agent. - Scripts need to run without any user interaction. @@ -764,18 +766,99 @@ of the controls. This means that a Home Assistant user not associated with the device user running the agent can use the exposed controls to issue potentially disruptive actions on a device that another user is accessing. -[:arrow_up: Back to Top](#notebook_with_decorative_cover-table-of-contents) +[⬆️ Back to Top](#notebook_with_decorative_cover-table-of-contents) - -## :compass: Roadmap +## ⚙️ Building/Compiling Manually -Check out [what I'm working -on](https://github.com/joshuar/go-hass-agent/discussions/150) for future -releases. +### Build Requirements -[:arrow_up: Back to Top](#notebook_with_decorative_cover-table-of-contents) +Go Hass Agent uses [Mage](https://magefile.org/) for development. Make sure you +follow the instructions on the Mage website to install Mage. + +### Compiling + +Use the following mage invocation in the project root directory: + +```shell +mage -d build/magefiles -w . build:full +``` + +This will: + +- Run `go mod tidy`. +- Run `go fmt ./...`. +- Run `go generate ./...`. +- Build a binary and place it in `dist/go-hass-agent-amd64`. + +To just build a binary, replace `build:full` with `build:fast` in the mage +invocation above. + +### Cross Compilation + +Go Hass Agent can also be built for **arm (v6/v7)** and **arm64** with +cross-compilation. **This is only supported on Ubuntu as the host for +cross-compiles**. To build for a different architecture, set the `BUILDPLATFORM` +environment variable: + +```shell +export BUILDPLATFORM=linux/arm64 # or linux/arm/v6 or linux/arm/v7 +``` + +Install the target architecture libraries for cross-compilation: + +```shell +mage -d build/magefiles -w . preps:deps +``` + +Then the commands for building and packaging above should work as expected. + +> [!NOTE] +> The devcontainer has all the necessary compilers and libraries +> installed for cross-compilation. + +### Packages + +Go Hass Agent uses [nfpm](https://nfpm.goreleaser.com/) to create +packages for Fedora, Arch, and Ubuntu and +[fyne-cross](https://github.com/fyne-io/fyne-cross) to create packages for +Debian and Linux distributions with older libraries. + +To build packages, use the following invocations: + +```shell +mage -v -d build/magefiles -w . package:nfpm +mage -v -d build/magefiles -w . package:fyneCross +``` + +The above mage actions will install the necessary tooling for packaging, if +needed. + +- Packages built with `nfpm` will be available under the `dist/` folder. +- Packages built with `fyne-cross` will be available under `fyne-cross/dist/linux-*/`. +- You can build packages for other architectures as well by following the guide + for [cross-compliation](#cross-compilation). + +### Container Images + +A Dockerfile that you can use to build an image can be found [here](../../Dockerfile). + +You can build an image with a command like the following (using Podman): + +```shell +podman build --file ./Dockerfile --network host --tag go-hass-agent +``` + +As with building a binary, +[cross-compliation](https://docs.docker.com/build/building/multi-platform/#cross-compilation) +is supported: + +```shell +# use eitherlinux/arm64, linux/arm/v7 +podman build --file ./Dockerfile --build-arg BUILDPLATFORM=linux/arm64 --build-arg TARGETARCH=arm64 --network host --tag go-hass-agent +``` + +[⬆️ Back to Top](#notebook_with_decorative_cover-table-of-contents) - ## :wave: Contributing - Found an issue? Please [report @@ -786,14 +869,33 @@ releases. - Want to help develop Go Hass Agent? See the [contributing guidelines](CONTRIBUTING.md). - -### :scroll: Code of Conduct +## 💾 Committing Code + +This repository is using [conventional commit +messages](https://www.conventionalcommits.org/en/v1.0.0/#summary). This provides +the ability to automatically include relevant notes in the +[changelog](../CHANGELOG.md). The [TL;DR](https://en.wikipedia.org/wiki/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. + +### 📜 Code of Conduct Please read the [Code of Conduct](https://github.com/joshuar/go-hass-agent/blob/master/CODE_OF_CONDUCT.md) -[:arrow_up: Back to Top](#notebook_with_decorative_cover-table-of-contents) +[⬆️ Back to Top](#notebook_with_decorative_cover-table-of-contents) + +## 🧭 Roadmap + +Check out [what I'm working +on](https://github.com/joshuar/go-hass-agent/discussions/150) for future +releases. + +[⬆️ Back to Top](#notebook_with_decorative_cover-table-of-contents) - ## :grey_question: FAQ ### _Can I change the units of the sensor?_ @@ -878,19 +980,19 @@ should start with every boot. - For other init systems, consult their documentation on how to enable and run user services. -[:arrow_up: Back to Top](#notebook_with_decorative_cover-table-of-contents) +[⬆️ Back to Top](#notebook_with_decorative_cover-table-of-contents) -## :gem: Acknowledgements +## 🤝 Acknowledgements - [Home Assistant](https://home-assistant.io). - This [Awesome README Template](https://github.com/Louis3797/awesome-readme-template). -[:arrow_up: Back to Top](#notebook_with_decorative_cover-table-of-contents) +[⬆️ Back to Top](#notebook_with_decorative_cover-table-of-contents) -## :warning: License +## 🧑‍⚖️ License [MIT](LICENSE) -[:arrow_up: Back to Top](#notebook_with_decorative_cover-table-of-contents) +[⬆️ Back to Top](#notebook_with_decorative_cover-table-of-contents) diff --git a/build/scripts/enable-multiarch b/build/scripts/enable-multiarch index 4a1ae9b87..4c4c2dd49 100755 --- a/build/scripts/enable-multiarch +++ b/build/scripts/enable-multiarch @@ -7,6 +7,7 @@ set -e +# set pkgarch as per given BUILDPLATFORM case $1 in linux/amd64) exit 0 ;; linux/arm/*) pkgarch=(armhf) ;; @@ -17,11 +18,14 @@ esac function join_by { local IFS="$1"; shift; echo "$*"; } +# ensure the existing defualt repos are only consulted for amd64 arch sed -i 's|^deb\s|deb [arch=amd64] |g' /etc/apt/sources.list +# add the additional arch for arch in "${pkgarch[@]}"; do dpkg --add-architecture ${arch} done archs=$(join_by , "${pkgarch[@]}") +# add repos for the additional arch tee -a /etc/apt/sources.list << EOF deb [arch=${archs}] http://ports.ubuntu.com/ubuntu-ports/ jammy main #deb-src [arch=${archs}] http://ports.ubuntu.com/ubuntu-ports/ jammy main diff --git a/build/scripts/install-build-deps b/build/scripts/install-build-deps index f95c5e099..df6ec1ed3 100755 --- a/build/scripts/install-build-deps +++ b/build/scripts/install-build-deps @@ -18,6 +18,7 @@ esac export DEBIAN_FRONTEND=noninteractive +# install build dependencies as per given arch apt-get update apt-get -y install desktop-file-utils pkg-config git ${ccpkg[@]:0} for a in "${arch[@]}"; do diff --git a/build/scripts/install-run-deps b/build/scripts/install-run-deps index 8979a160d..77038cdbd 100755 --- a/build/scripts/install-run-deps +++ b/build/scripts/install-run-deps @@ -18,6 +18,7 @@ esac export DEBIAN_FRONTEND=noninteractive +# install runtime dependencies as appropriate for given arch apt-get update for a in "${arch[@]}"; do apt-get -y install \ diff --git a/docs/development/README.md b/docs/development/README.md index fea6644a6..7ce9ffc15 100644 --- a/docs/development/README.md +++ b/docs/development/README.md @@ -7,13 +7,6 @@ # Go Hass Agent Development Notes -## Build Requirements - -Go Hass Agent uses [Mage](https://magefile.org/) for development. Make sure you -follow the instructions on the Mage website to install Mage. If you are using -the devcontainer (see below), this is already installed. - - ## Development Environment It is recommended to use [Visual Studio Code](https://code.visualstudio.com/). @@ -36,100 +29,6 @@ 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 - -Use the following mage invocation in the project root directory: - -```shell -mage -d build/magefiles -w . build:full -``` - -This will: - -- Run `go mod tidy`. -- Run `go fmt ./...`. -- Run `go generate ./...`. -- Build a binary and place it in `dist/go-hass-agent-amd64`. - -To just build a binary, replace `build:full` with `build:fast` in the mage -invocation above. - -### Packages - -Go Hass Agent uses [nfpm](https://nfpm.goreleaser.com/) to create -packages for Fedora, Arch, and Ubuntu and -[fyne-cross](https://github.com/fyne-io/fyne-cross) to create packages for -Debian and Linux distributions with older libraries. - -To build packages, use the following invocations: - -```shell -mage -v -d build/magefiles -w . package:nfpm -mage -v -d build/magefiles -w . package:fyneCross -``` - -The above mage actions will install the necessary tooling for packaging, if -needed. - -Packages built with `nfpm` will be available under the `dist/` folder. -Packages built with `fyne-cross` will be available under `fyne-cross/dist/linux-amd64/`. - - -### 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, set the `TARGETARCH` -environment variable: - -```shell -export TARGETARCH=arm # or arm64 -``` - -Install the target architecture libraries for cross-compilation: - - -```shell -mage -d build/magefiles -w . preps:deps -``` - -Then the commands for building and packaging above should work as expected. - -> [!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](../../Dockerfile). - -You can build an image with a command like the following (using Podman): - -```shell -podman build --file ./Dockerfile --network host --tag go-hass-agent -``` - -As with building a binary, -[cross-compliation](https://docs.docker.com/build/building/multi-platform/#cross-compilation) -is supported by specifying a `--platform=$BUILDPLATFORM` argument: - -```shell -podman build --platform=arm64 --file ./Dockerfile --network host --tag go-hass-agent -``` - -## Committing Code - -This repository is using [conventional commit -messages](https://www.conventionalcommits.org/en/v1.0.0/#summary). This provides -the ability to automatically include relevant notes in the -[changelog](../CHANGELOG.md). The [TL;DR](https://en.wikipedia.org/wiki/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