Skip to content

Typescript utilities for creating and managing virtual entities within Home Assistant

License

Notifications You must be signed in to change notification settings

Digital-Alchemy-TS/synapse

Repository files navigation

stars discord

codecov version

📘 Description

Welcome to @digital-alchemy/synapse!

This project builds on the functions provided by @digital-alchemy/hass to provide the ability to generate entities within your Home Assistant install. With the help of a custom component, you can gate logic behind switches, report states with sensors, attach functions to buttons, and more!

💾 Install

You can install the custom component through HACS. See the repo for more detailed install instructions of the component: https://github.com/Digital-Alchemy-TS/synapse-extension

This library can be installed as a simple dependency

npm i @digital-alchemy/synapse @digital-alchemy/hass

Then add to your application / library

import { LIB_SYNAPSE } from "@digital-alchemy/synapse";
import { LIB_HASS } from "@digital-alchemy/hass";

// application
const MY_APP = CreateApplication({
  libraries: [LIB_SYNAPSE, LIB_HASS],
  name: "home_automation",
})

// library
export const MY_LIBRARY = CreateLibrary({
  depends: [LIB_SYNAPSE, LIB_HASS],
  name: "special_logic",
})

🛠️ Operation

Creating new entities with the library is easy! The library will automatically handle communication with Home Assistant, reporting values, and attaching callbacks

import { CronExpression, TServiceParams } from "@digital-alchemy/core";
import { faker } from "@faker-js/faker";

export function Example({ scheduler, context, synapse }: TServiceParams) {
  // create a new switch entity
  const useHacker = synapse.switch({ context, name: "Use hacker phrase" });
  // create a new sensor entity
  const sensor = synapse.sensor({ context, name: "Current catchphrase" });

  // create a new phrase
  // taking into consideration the current state of the switch
  const regenerate = () => {
    sensor.storage.set(
      "state",
      useHacker.state === "on"
        ? faker.hacker.phrase()
        : faker.company.catchPhrase()
    );
  };

  // update sensor every 10 minutes
  scheduler.cron({
    exec: regenerate,
    schedule: CronExpression.EVERY_10_MINUTES,
  });

  // provide a button for immediate updates
  synapse.button({
    context,
    exec: regenerate,
    name: "Update phrase",
  });
}

🤝 Related Projects

GitHub Description NPM
automation Advanced automation tools for creating dynamic workflows. @digital-alchemy/automation
type-writer Generate custom type definitions for your setup. @digital-alchemy/type-writer
automation-template Start your own Home Automation project with the @digital-alchemy quick start template