Automation Rules

This article is a work in progress! This process will be moved to the a simple web interface.

Automation rules allow users to quickly write powerful rules using a single format. To get started, create a file called “automation.txt” in the root directory of the Yombo gateway software. An *important term* to learn is: *platform*. The platform directs sources, filters, and actions to specific components within the Yombo gateway framework. See below for a list of platforms included within the gateway, however, modules can extend the capabilities by adding additional ‘platforms’ to routes.

Related Items

Usage

First, lets start off with a basic, very minimal outline of a rule. You can always copy/paste from here into your automation.txt file when you need to add an additional rule.

rules: [
  {
  name: my first rule
  description: This rule will do many things, but it won't make toast.
  trigger: {
    source: {
        platform:
        }
    filter: {
        platform: basic_values
        }
    }
  # optional, default is and. Sets if the conditions are and or or'd together.
  condition_type: and

  # Only fire this rule if the Operating system is running linux!
  condition: [
    {
    source: {
        platform:
        name:
        }
    filter: {
        platform:
        }
    }
    ]

  # actions allow us to do something after rule triggers and
  # conditions allow it.
  action: [
    {
    platform:
    # we can use any type of delay, or even a time: 11:34:10am
    delay: 20m 20 seconds
    }
  ]
  }
]

Breaking down the three three primary sections of a rule:

  • Trigger – A trigger is what fires off the rule. Without a trigger, no action can take place.
  • Conditions – Conditions place restrictions if the rule should activate. You can place any additional conditions as needed, including multiple conditions.
  • Actions – Actions to be performs are placed here. Multiple actions can take place. For example, at night, you might turn on some lights, but after 4 hours, you might turn them back off.

Sources and Filters

Triggers and conditions require two things: a source and a filter. Think of it like this: the source collects a value and stores that value to pass to the filter. The filter than makes sure it has a value that you want.

The ‘source’ portion of a trigger or condition (they are not allowed in actions) tells the Yombo gateway where to collect a value. Once a value is collected, a comparison need to be performed.

Actions

To be completed.

Included Platforms

The platform directs sources, filters, and actions to specific components within the Yombo framework. Module developers can add additional platforms and will be documented within their module. Here is a list of platforms included within the Yombo gateway.

Atoms

  • Platform Name: atoms
  • Rule portions supported: sources, filters, actions

Automation rules allow users to quickly write powerful automation rules. To get started, create a file called “automation.txt” in the root directory of the Yombo gateway softwareThe [[Atoms]] library implements an atoms platform to allow automation rules access to atom information, as well as perform actions; such as setting atom values.

  • Sources – The following fields are defined (* = required):
    • name * – The name of the atom for the value you want to send to the filter.
  • Actions – The following fields are defined (* = required):
    • name * – The name of the atom for the value you want to send to the filter.

Basic Values

  • Platform Name: basic_values
  • Rule portions supported: sources, filters

The platform “basic_values” can perform basic comparisons.

  • Filters – The following fields are defined (* = required):
    • value * – The comparison value to check
    • type – The type of comparison (== is default): ==, !=, >=, <=, >, < *or* eq, ne, ge, le, gt, lt

Call Function (Advanced)

  • Platform Name: call_function
  • Rule portions supported: action (support for filters is planned.)

An advanced platform that allows you to call a specific function within the Yombo gateway framework; typically used in conjunction with a custom module. This would typically only be used for a function that you created.

There are two methods for referring to the function to call: by name or by passing a callable as a value to the rule.

TO BE COMPLETED.

States

  • Platform Name: states
  • Rule portions supported: sources, filters, actions

The [[States]] library implements a states platform to allow automation rules access to state information, as well as perform actions; such as setting state values.

  • Sources – The following fields are defined (* = required):
    • name * – The name of the state for the value you want to send to the filter.
    • password – If a password is required to read the state, include it.
  • Actions – The following fields are defined (* = required):
    • name * – The name of the state for the value you want to send to the filter.
    • password* – If a password is required to write the state, include it.

Additional Example


rules: [
  {
  name: my first rule
  description: This rule will do many things, but it won't make toast.

  # the trigger defines what makes this rule fire. For now, we will
  # will just turn on a light when it's dark
  trigger: {
    # lets define the source first. Where should we get our value from.
    source: {
        # a platform is a way to note what module or library the
        # data is coming from. Users can write modules to create
        # even more advanced modules or a module can even define
        # a new platform.

        # Says: From the states library, monitor the "times_dark"
        # state for any changes.
        platform: states
        name: times_dark
        }

    # Once a source value is available, lets do some filtering.
    filter: {
        # We want it to be dark. Any value here will work: 1, true, yes
        platform: basic_values
        value: 0
        }
    }

  # Conditions allow us to apply additional filters and can be and or
  # or'd together
  condition_type: and

  # Only fire this rule if the Operating system is running linux!
  condition: [
    {
    source: {
        platform: atoms
        name: kernel
        }
    filter: {
        platform: basic_values
        value: linux
        }
    }
    ]

  # actions allow us to do something after rule triggers and
  # conditions allow it.
  action: [
    {
    platform: devices
    device: christmas tree
    command: on
    }
    # a second action to turn off water fountain!
    {
    platform: devices
    device: christmas tree
    command: off
    # lets turn this off after 2 hours. can use (s)econds, (m)inutes, (h)ours.
    delay: 2h
    # time: 11:00pm  # OR we can simply just specify the time.
    }
  ]
  }
  {
  name: my first rule
  description: This rule will do many things, but it won't make toast.

  # the trigger defines what makes this rule fire. For now, we will
  # will just turn on a light when it's dark
  trigger: {
    # lets define the source first. Where should we get our value from.
    source: {
        # a platform is a way to note what module or library the
        # data is coming from. Users can write modules to create
        # even more advanced modules or a module can even define
        # a new platform.

        # Says: From the states library, monitor the "times_dark"
        # state for any changes.
        platform: states
        name: automationexample
        }

    # Once a source value is available, lets do some filtering.
    filter: {
        # We want it to be dark. Any value here will work: 1, true, yes
        platform: basic_values
        value: 0
        }
    }

  # Conditions allow us to apply additional filters and can be and or
  # or'd together
  condition_type: and

  # Only fire this rule if the Operating system is running linux!
#  condition: [
#    {
#    source: {
#        platform: atoms
#        name: kernel
#        }
#    filter: {
#        platform: basic_values
#        value: linux
#        }
#    }
#    ]

  # actions allow us to do something after rule triggers and
  # conditions allow it.
  action: [
    {
    platform: devices
    device: christmas tree
    command: on
    }
    # a second action to turn off water fountain!
    {
    platform: devices
    device: christmas tree
    command: off
    # lets turn this off after 2 hours.
    # Can use english like:
    # 2hours 2seconds  - will delay by 2 hours and 2 seconds
    # 11pm - will issue command at 11pm
    delay: 5s
    }
  ]
  }
]