Hey all! Wanted to put my project out for people to check out, have a dedicated Lemmy community (!general@lemmy.digital-alchemy.app) that I’ll be more active in for posting updates and answering more library specific questions.

What is this project?

@digital-alchemy is a set of extensions that take advantage of the NestJS direction injection framework to provide custom bootstrapping logic and provider logic. It contains libraries to cover terminal apps, home automation, and more.

Current Module State

I’ve been personally using / developing the proxy api bindings for almost 2 years now. The basic proxy api type generation and bindings are stable, with only add minor features and type enhancements are really expected in the future. I appreciate my waking up to working automation setups, so this library has a lot of attention given to stability and anti foot-gun features.

Entity generation is still on the experimental side. The most useful to me domains are implemented, but the rest are planned, along with some potential internal architectural updates.

Basic Concept

The best comparison for the niche this library fills is against Node Red. It will expose a combination of rest api & websocket endpoints in a way that enables application logic to be written. The @digital-alchemy/automation-logic

This library will pull from the active running configuration in your Home Assistant install, and set up a bunch of type definitions to match it. All entities will be present, and all services will be explicitly listed with all their parameters and filters for valid entities. It then will emit events through a series of eventemitter bindings, and make available services through a javascript proxy api.

Module Goals / Scope

The @digital-alchemy/home-assistant library is part of a larger repo which contains additional, more opinionated, Home Automation related modules. This library aims to be a lower level library, doing more basic transformations and convenience tooling

Rest API

A basic typescript friendly wrapper is provided for the Home Assistant. It covers most of the common interactions and information requests that can be performed from the Lovelace UI. Retrieving logs, searching calendars, configuration interactions, etc.

Not super exciting, but it covers some of the oddball interactions not available within the websocket

Websocket API

If you really really want to, the raw socket is available for interactions. That method of interaction is discouraged in favor of using the higher level proxy api tooling. These sit on top of the connection, maintaining a local copy of entity states, formatting valid commands, and passing through events to trigger logic through more readable bindings.

Push Entity Generation

The library also has the ability to generate new permanent entities within Home Assistant. This gives them unique ids, which allows them to be persisted through reboots and properly track history. Currently, this is accomplished by generating template entities and including them as a YAML package in your Home Assistant configuration. This feature requires a http receiver to be available in your app for rest calls to talk back to.

Support is currently limited to these domains, but the rest will be added as time permits:

  • switch
  • binary_sensor
  • sensor
  • button

Example Code

Hass CLI

This application is based off @digital-alchemy/tty, and provides a spot to test stuff in an easy to debug spot for myself. It isn’t intended to be extremely functional, but some features may be added in the future as the need / requests arise

Home Automation

A standalone repo, suitable for forking and messing around with. It runs as a standalone NodeJS application, and utilizes @digital-alchemy/automation-logic to arrange logic into rooms, create scenes, and manage concepts as higher level elements.

Much of the code here is lazily copied from my running setup earlier in the year, and slightly tweaked to fit into a single application repo instead of a second monorepo. It contains a lot of examples of small automations, scene creation, device trigger based eventing, and a few other things