Skip to content

songokas/hvents

BranchesTags

Repository files navigation

About

Very simple event automation system to manage home events easily by defining it in a configuration file

Supports:

  • time events
  • mqtt events
  • http events
  • file events
  • external commands

How to install

Install deb

amd64

wget https://github.com/songokas/hvents/releases/download/v0.5.1/hvents_0.5.1_amd64.deb \
  && sudo apt install ./hvents_0.5.1_amd64.deb

armhf

wget https://github.com/songokas/hvents/releases/download/v0.5.1/hvents_0.5.1_armhf.deb \
  && sudo apt install ./hvents_0.5.1_armhf.deb

arm64

wget https://github.com/songokas/hvents/releases/download/v0.5.1/hvents_0.5.1_arm64.deb \
  && sudo apt install ./hvents_0.5.1_arm64.deb

Download binary

https://github.com/hvents/releases

Install from source

cargo install --bins --root=. --git=https://github.com/songokas/hvents

How to configure and run

Start with a minimal configuration

# events.yaml
events:
  schedule_print:
    time: in 5 seconds
    data: Executed every 5 seconds
    next_event: print_to_stdout
  print_to_stdout:
    print: stdout

start_with:
  - schedule_print

Run

hvents events.yaml

Add more events as needed

Configuration options

Create a global configuration file:

# events.yaml

# events are loaded from specified files with prefix from the key
# optional
groups:
  hall: events/hall.yaml
  weather: events/weather.yaml

# events are loaded from specified files
# optional
event_files:
  - doors.yaml

# events defined in the same configuration file
# optional
events:
  movement:
    mqtt_subscribe:
      topic: security/hall/movement
      body: "True"
    next_event: light_on
  light_on:
    mqtt_publish:
      topic: cmnd/hall/Power
      body: on

# specify which events to start with
start_with:
  - movement

# configure mqtt clients
# optional
mqtt:
  default: # pool_id - defines which client to use for mqtt events
    host: host
    port: 1883 # optional
    user: user # optional
    pass: pass # optional
    client_id: homeevents # optional

# host and port to listen on for api_listen events
# optional
http:
  # default is the pool id used for api_listen events
  default: 127.0.0.1:8991

# restore events from the directory specified, between startups
# optional, no restore by default
restore: data/

# specify location for sunrise, sunset calculations
# optional
location:
  latitude: 52.37403
  longitude: 4.88969

# specify devices to read scancodes from
# optional
devices:
  default: /dev/input/event0

# enable metrics
# optional
metrics:
  instance_id: unique-service-id

Run

Manually

hvents events.yaml

With systemd

Working directory /opt/hvents

systemctl start hvents

Available events

Publish to mqtt topic

Publish to topic with body from even.data

mqtt_publish: announce/back-door
mqtt_publish:
  topic: announce/back-door
  body: back door open # optional event.data will be used if template is not defined
  pool_id: default # optional client to use for publishing events

Publish event can use handlebar templates to define a body as well

mqtt_publish:
  topic: announce/weather
  body: '{{#each forecastTimestamps}}{{#if (eq forecastTimeUtc (date-time-format ../forecastToShow "%Y-%m-%d %H:%M:%S"))}}Air temperature {{airTemperature}} degrees{{/if}}{{/each}}'

Subscribe to mqtt topic

mqtt_subscribe: security/back-door/open

Mqtt request body must match exactly

mqtt_subscribe:
  topic: security/back-door/open
  body: "True"
  pool_id: default # optional, client to use for publishing events

Mqtt request body must contain a string to match

mqtt_subscribe:
  topic: security/back-door/open
  body_contains: "special string"

Read from file

file_read: /tmp/file
file_read:
  file: /tmp/file
  # options: string,json,bytes
  # optional
  data_type: string

Write to file

File will be written with data provided by the previous event or event.data defined in its own configuration

file_write: /tmp/file
file_write:
  file: /tmp/file
  # options: truncate,append
  mode: truncate # default

Call API endpoint

api_call: https://api.meteo.lt/v1/places/vilnius/forecasts/long-term
api_call:
  url: https://api.meteo.lt/v1/places/vilnius/forecasts/long-term
  # optional
  headers:
    X-HEADER: value
  # options: get,post,put,delete
  method: get # optional
  # options: json,text,bytes
  request_content: json # optional
  # request body template to be rendered
  request_body: "{{client_id}}" #optional (event.data is used if not provided)
  # options: json,text,bytes
  response_content: json # optional

Listen for API call

Listen for an http call

event.data or response_body can be used to control what to return as a response

api_listen:
  path: /clients/1
  # options: get,post,put,delete
  method: get # optional
  # options: json,text,bytes
  request_content: json # optional
  # expected request headers (must match at least one of the array item fully)
  # optional
  request_headers:
    - Authorization: Basic 3amd
      Test: 1
    - Authorization: Basic 3mdk
  # options: json,text,bytes
  response_content: json # optional
  # response template to be rendered
  response_body: "{{client_id}}" #optional
  pool_id: default # optional references which http server handles the request

Keys available in a response body template:

  • request
  • url
  • segments (http request url split by /)
  • data

File changes

file_changed:
  path: /tmp/a
  # options: created, written, removed
  when: created # optional
watch:
  path: /tmp
  # options: start, stop
  action: start # optional
  recursive: false # optional

Schedule at specific time

Execute event at 8:00:00

time: 8:00

Execute event at 8:00:00 with event id

time:
  execute_time: 8:00
  event_id: time_events # event id can be used to overwrite a previous event with the same id

Scheduling the same event will overwrite the previous event.

All times are in local timezone.

Available date time format can be found on https://lib.rs/crates/human-date-parser#readme-formats

Additional formats supported:

  • sunset
  • sunset in 1 hours
  • sunrise
  • sunrise in 20 seconds

Schedule at specific time and repeat

Execute event at 8:00:00 and repeat tomorrow 8:00:00

repeat: 8:00

Allow event only for specific times

Allow event execution only at specific times

period:
  from: 8:00
  to: 10:00

Execute command

Execute external command

Command takes input from the previous event data

execute:
  command: date
  # optional
  args: ["--utc"]
  # render template and replace arguments by index
  # optional
  replace_args:
    0: "--local"
  # options: string,json,bytes
  # optional
  data_type: string
  # provide environment variables
  # optional
  vars:
    ENV_VARIABLE_KEY: value

Read scan codes from the device

scan_code_read: 0x7a1a

devices needs to be defined globally

Apply comparison

Apply comparison operation and if it matches execute next event

comparison:
   data_to_compare: state
   key: test
   operation": lt
   value: 15

Template data

Unless otherwise stated keys available in templates

  • data
  • metadata
  • state

Template helpers available

{{date-time-format "2022-02-02" "%Y-%m-%d"}} - format date and time

{{otlp-metrics 600}} - output metrics that changed <= 600 seconds ago

{{lookup-word "1 2 3" 1 " "}} - lookup word by index after splitting it with a delimiter

default handlebar helpers

Event references and data

Each event can reference a next event and define its data, which is merged together as it goes through the chain depending on the merge policy

  • merge_data: yes - always try to merge data
  • merge_data: no - do not merge data
  • merge_data: overwrite - overwrite any data defined for the event
  • merge_data: yes_if_empty - merge data only if no data is defined for the event

example:

subscribe:
  mqtt_subscribe:
    topic: weather/data
    body_contains: "forecast"
  next_event: schedule_writing
schedule_writing:
  time: 8:00
  data: schedule_writing_data
  merge_data: yes
  next_event: write_to_file
write_to_file:
  file_write: /tmp/test3
  data: write_to_file_data
  merge_data: yes

would write

#/tmp/test3
forecast 22.2
schedule_writing_datawrite_to_file_data

Event examples

examples

About

Home automation by configuration

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases 10

Gherkin syntax support Latest
Mar 17, 2026
+ 9 releases

Packages

 
 
 

Contributors

Languages