diff --git a/README.md b/README.md index c09eb478..84cfdc7b 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,7 @@ Easiest way is to run pip as a module ( +- - TIP: comment out the `git-committers` and `git-revision-date-localized` sections in `mkdocs.yml` to speed up the build and prevent exceeding the GitHub API calls, but remember to uncomment it before committing ## Deploying manually diff --git a/docs/Configuring.md b/docs/Configuring.md index 7db5262d..cacf9b9f 100644 --- a/docs/Configuring.md +++ b/docs/Configuring.md @@ -168,31 +168,34 @@ The scheduler can also be used to periodically set values based on another entit ### Conditions -Introduced in **version 3.7**, the Scheduler has been extended to support conditional statements used in the `Command` and/or `Value` fields. Conditions have a strict syntax (see below) and are evaluated every 10 seconds. The condition is only executed when the condition changes from false to true. This is powerful new feature and allows, for example, to set a schedule based on a condition, or to set a value based on a condition. +Introduced in **version 3.7**, the Scheduler has been extended to support conditional statements and formulas that can be used in the `Command` and/or `Value` fields for Timer, On Change and Condition types. + +Conditions have a strict syntax (see below) and are evaluated every 10 seconds. The condition is only executed when the condition changes from false to true. This is powerful new feature and allows, for example, to set a schedule based on a condition or set a value based on a condition. Pay attention to the following rules: - a condition has to be a logic value `0` or `1`, the condition is `true` only for `1`, an arithmetic result `1` is also interpreted as `true` schedule command executed for `3 > 2, 3 - 2` schedule command not executed for `3 < 2`, `3 + 2` -- blanks are not needed, but makes the formula more readable -- EMS-ESP values are accessed `/` or `//value`, `` may contain prefixes like ``. -- checking enum and bool values depends on the user's API setting! Check the right value before setting a schedule - e.g. check output to see if building = "medium", create the rule with `thermostat/building == medium` - also for boolean values check if you have to use `0/1`, `off/on`, `OFF/ON`, or `false/true` -- strings containing special characters have to be written in quotations, e.g. `boiler/pumpmode == "delta-P2"`, to avoid a calculation error on delta minus P2, - other strings can be written with or without quotations +- spaces are not needed, but makes the formula more readable +- EMS-ESP values are accessed `/` or `//value`. The `` may contain additional prefixes like ``. +- The user's Boolean Format (`0/1`, `off/on`, `OFF/ON`, or `false/true`) and Enum Format (value/index) Settings are used when evaluating bool and enums. Check the right value before setting a schedule by querying the API directly. For example go to `http://ems-esp.local/api/thermostat` to see if building is "medium", then create the rule with `thermostat/building == medium`. +- strings containing special characters have to be quoted. e.g. `boiler/pumpmode == "delta-P2"`, to avoid a calculation error on delta minus P2. - all strings are converted to lowercase - commands followed by a divider (`/`) have to be set in parenthesis e.g. `(boiler/seltemp)/2` - condition command is only executed on a change of the condition from `false` to `true`. If the condition stays true, the command is not repeated -- command value can also be a formula +- a command Value can also be a formula - allowed operations: + - arithmetic: `+` `-` `*` `/` `%` - - prefix: `-` `round` `abs` `int` `exp` `log` `sqrt` `pow` + - functions: `round` `abs` `int` `exp` `log` `sqrt` `pow` - logic: `==` `!=` `<=` `>=` `<` `>` `&&` `||` - - prefix: `!` - - conditional operations: ` ? : ` only surrounding a formula, not within a formula (not allowed: `5 + ( ? : )`, allowed: ` ? 5 + : 5 + `), cascaded conditions can be used (` ? ? : : ? : `) -- on change trigger is always one or more entities `/`, where device is **not** system. It can have multiple triggers. e.g. `boiler/outdoortemp custom/setpoint` and triggers on change of each value (entities never change the same time (it's a callback) and logical operations here like `&&` makes no sense) + - prefix: `!` (not) and `-` (negation) + - conditional operations: ` ? : ` only surrounding a formula, not within a formula. Examples: + - (allowed) ` ? 5 + : 5 + ` + - (not allowed) `5 + ( ? : )` and cascaded conditions ` ? ? : : ? : ` + +An On Change trigger is a list of entities following the format `/`. Note, a `` of "system" is not supported. e.g. `boiler/outdoortemp custom/setpoint`. As entities never change at the same time using logical operations here like `&&` aren't useful. ![Web](_media/screenshot/web_conditions_1.png) diff --git a/mkdocs.yml b/mkdocs.yml index 7247db46..61e58ba5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -15,10 +15,10 @@ plugins: - redirects: redirect_maps: - table-reader - - git-revision-date-localized - - git-committers: - repository: emsesp/docs - branch: main + # - git-revision-date-localized + # - git-committers: + # repository: emsesp/docs + # branch: main # - htmlproofer # strict: true @@ -64,22 +64,26 @@ markdown_extensions: toc_depth: 3 - pymdownx.tabbed: alternate_style: true - # - pymdownx.emoji: - # emoji_index: !!python/name:material.extensions.emoji.twemoji - # emoji_generator: !!python/name:material.extensions.emoji.to_svg - pymdownx.betterem - pymdownx.caret - pymdownx.details - - pymdownx.highlight + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg + - pymdownx.highlight: + linenums: true - pymdownx.keys - pymdownx.mark - pymdownx.superfences - pymdownx.snippets - pymdownx.tilde + - pymdownx.details - meta - def_list - attr_list - md_in_html + # support pad width = 2, as formatted with prettier + - mdx_truly_sane_lists extra_css: - 'assets/css/anchor-fix.css' diff --git a/requirements.txt b/requirements.txt index baa15914..9d1506ef 100644 --- a/requirements.txt +++ b/requirements.txt @@ -10,3 +10,6 @@ mkdocs-git-revision-date-localized-plugin>=1.1.0 mkdocs-git-committers-plugin-2 git+https://github.com/cmitu/mkdocs-altlink-plugin.git lxml +mdx-truly-sane-lists==1.3 +mkdocs-material-extensions==1.0.3 +pymdown-extensions==9.1 \ No newline at end of file