Welcome to `@digital-alchemy/automation`!
npm install @digital-alchemy/automationWelcome to @digital-alchemy/automation!
This project builds on the utilities provided by @digital-alchemy/hass & @digital-alchemy/synapse to create home automation focused utilities for easily coordinating entities.
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
``bash`
npm i @digital-alchemy/automation @digital-alchemy/synapse @digital-alchemy/hass
Then added to your project
`typescript
import { LIB_AUTOMATION } from "@digital-alchemy/automation";
import { LIB_HASS } from "@digital-alchemy/hass";
import { LIB_SYNAPSE } from "@digital-alchemy/synapse";
import { LIB_FASTIFY } from "@digital-alchemy/fastify-extension";
// application
const MY_APP = CreateApplication({
libraries: [LIB_HASS, LIB_SYNAPSE, LIB_AUTOMATION, LIB_FASTIFY],
name: "home_automation",
})
// library
export const MY_LIBRARY = CreateLibrary({
depends: [LIB_HASS, LIB_SYNAPSE, LIB_AUTOMATION],
name: "special_logic",
})
`
Create rooms, with the ability to coordinate sets of entities together in scenes.
`typescript
import { CronExpression, TServiceParams } from "@digital-alchemy/core";
export function ExampleRoom({
automation,
scheduler,
hass,
context,
}: TServiceParams) {
// generate a room with scenes, sensors, etc
const room = automation.room({
context,
name: "Example",
scenes: {
high: {
definition: {
"light.ceiling_fan": { brightness: 255, state: "on" },
},
friendly_name: "High",
},
off: {
definition: {
"light.ceiling_fan": { state: "off" },
},
friendly_name: "Off",
},
},
});
// easy bindings for setting scene
scheduler.cron({
exec: () => (room.scene = "high"),
schedule: CronExpression.EVERY_DAY_AT_8AM,
});
// or set it through the service
scheduler.cron({
exec: async () => await hass.call.scene.turn_on({
entity_id: "scene.example_off"
}),
schedule: CronExpression.EVERY_DAY_AT_8PM,
});
return room;
}
`$3
Sometimes devices don't get the message the first time. Other times a pesky human comes by and bumps a switch, turning off a switch that really should be left on. @digital-alchemy/automation provides several tools to help ensure devices know what they "should" be.
Scenes defined by rooms will periodically recheck entity states in their listed definitions, ensuring that the device state matches your description of what it should be. The library also provides tools for rules-based state management of switches.
`typescript
import { TServiceParams } from "@digital-alchemy/core";
export function ExampleRoom({ automation, context }: TServiceParams) {
// plant light should be on while the sun is up, but only until 5:30 PM
automation.managed_switch({
context,
entity_id: "switch.plant_light",
shouldBeOn() {
// check sun position
if (automation.solar.isBetween("dawn", "dusk")) {
return automation.time.isBefore("PM5:30")
}
return false;
},
});
}
`$3
By default for lights defined in room scenes, if no particular color is defined, the temperature will be automatically managed for you.
You can see the current light temperature as a dedicated sensor. Updates for light temperature are rate-limited with some configurable settings. This allows you to easily keep a natural feeling light temperature in your home, without overloading your install.
The library includes some utilities for translating a specific pattern of events in Home Assistant into callbacks. This can enable new layers of functionality remotes, allowing for creating automations based on button sequences.
| GitHub | Description | NPM |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| synapse | Tools for generating entities within Home Assistant. | @digitial-alchemy/synapse |
| 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 | |