Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Moved information about DateTime Group functions 'LATEST' / 'EARLIEST' #1206

Merged
merged 1 commit into from
Apr 28, 2020
Merged

Moved information about DateTime Group functions 'LATEST' / 'EARLIEST' #1206

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 2 additions & 18 deletions concepts/items.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,25 +49,9 @@ Example for a Group Item as a simple collection of other Items:
Group Items can derive their own state from their member Items.
To derive a state the Group Item must be constructed using a base Item and a Group function.
When calculating the state, Group functions recursively traverse the Group's members and also take members of subgroups into account.
If a subgroup however defines a state on its own (having base Item & Group function set) traversal stops and the state of the subgroup member is taken.
If a subgroup however defines a state on its own (having base Item & Group function set) traversal stops and the state of the subgroup member is taken.

Available Group functions:

| Function | Parameters | Base Item | Description |
|--------------------|-------------------------------|---------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| EQUALITY | - | \<all\> | Sets the state of the members if all have equal state. Otherwise UNDEF is set. In the Item DSL `EQUALITY` is the default and may be omitted. |
| AND, OR, NAND, NOR | <activeState>, <passiveState> | \<all\> (must match active & passive state) | Sets the \<activeState\>, if the member state \<activeState\> evaluates to `true` under the boolean term. Otherwise the \<passiveState\> is set. |
| SUM, AVG, MIN, MAX | - | Number | Sets the state according to the arithmetic function over all member states. |
| COUNT | <regular expression> | Number | Sets the state to the number of members matching the given regular expression with their states. |
| LATEST, EARLIEST | - | DateTime | Sets the state to the latest/earliest date from all member states |

Examples for derived states on Group Items when declared in the Item DSL:

- `Group:Number:COUNT(".*")` counts all members of the Group matching the given regular expression, here any character or state (simply count all members).
- `Group:Number:AVG` calculates the average value over all member states which can be interpreted as `DecimalTypes`.
- `Group:Switch:OR(ON,OFF)` sets the Group state to `ON` if any of its members has the state `ON`, `OFF` if all are off.
- `Group:Switch:AND(ON,OFF)` sets the Group state to `ON` if all of its members have the state `ON`, `OFF` if any of the Group members has a different state than `ON`.
- `Group:DateTime:LATEST` sets the Group state to the latest date from all its members states.
For available Group functions and examples see [Configuration Guide](../configuration/items.html#group-type).

## State and Command Type Formatting

Expand Down
44 changes: 26 additions & 18 deletions configuration/items.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -457,7 +457,7 @@ Because of the hierarchical structure of your group items, the rule will be clea
Additionally, the rule will not need to be modified when a new Item is added to the `Temperatures` group.

{: #group-type}
#### Group Type and State
### Derive Group State from Member Items

As you are now aware, an Item can have a state (e.g. "ON", "OFF").
A Group Item can also have a state.
Expand All @@ -474,17 +474,13 @@ Group[:itemtype[:function]] groupname ["labeltext"] [<iconname>] [(group1, group

Group state aggregation functions can be any of the following:

| Function | Description |
|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `EQUALITY` | Default if no function is specified. If ALL members have state X the group state will be X, otherwise the group state will be `UNDEF`. |
| `AND(value1,value2)` | [Boolean](https://en.wikipedia.org/wiki/Boolean_algebra) AND operation. If all item states are 'value1', 'value1' is returned, otherwise 'value2' is returned. |
| `OR(value1,value2)` | [Boolean](https://en.wikipedia.org/wiki/Boolean_algebra) OR operation. If at least one item state is of 'value1', 'value1' is returned, otherwise 'value2' is returned. |
| `NAND(value1,value2)` | [Boolean](https://en.wikipedia.org/wiki/Boolean_algebra) NAND (not AND) operation. Returns the opposite of the AND operation. |
| `NOR(value1,value2)` | [Boolean](https://en.wikipedia.org/wiki/Boolean_algebra) NOR (not OR) operation. Returns the opposite of the OR operation. |
| `AVG` | Calculates the numeric average over all Item states of decimal type. |
| `MAX` | Calculates the maximum value of all Item states of decimal type. |
| `MIN` | Calculates the minimum value of all Item states of decimal type. |
| `SUM` | Calculates the sum of all Item states in the Group. |
| Function | Parameters | Base Item | Description |
|----------------------------|-------------------------------|---------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `EQUALITY` | - | \<all\> | Default if no function is specified. Sets the state of the members if all have equal state. Otherwise `UNDEF` is set. In the Item DSL `EQUALITY` is the default and may be omitted. |
| `AND`, `OR`, `NAND`, `NOR` | <activeState>, <passiveState> | \<all\> (must match active & passive state) | [Boolean](https://en.wikipedia.org/wiki/Boolean_algebra) operation. Sets the \<activeState\>, if the members state \<activeState\> evaluates to `true` under the boolean term. Otherwise the \<passiveState\> is set. |
| `SUM`, `AVG`, `MIN`, `MAX` | - | Number | [Arithmetic](https://en.wikipedia.org/wiki/Arithmetic) operation. Sets the state according to the arithmetic function over all members states. |
| `COUNT` | <regular expression> | Number | Sets the state to the number of members matching the given regular expression with their states. |
| `LATEST`, `EARLIEST` | - | DateTime | Sets the state to the latest/earliest date from all members states |

Boolean group state functions additionally return a number representing the count of member Items of value 'value1' (see example below).

Expand All @@ -495,21 +491,33 @@ Incompatible Item types within a Group may result in the invalid aggregation res

**Examples:**

Examples for derived states on Group Items when declared in the Item DSL:

```java
Group:Number Lights "Active Lights [%d]" // e.g. "2"
Group:Switch:OR(ON,OFF) Lights "Active Lights [%d]" // e.g. ON and "2"
Group:Number:AVG Temperatures "All Room Temperatures [%.1f °C]" // e.g. "21.3 °C"
Group:Number Lights "Active Lights [%d]" // e.g. "2"
Group:Switch:OR(ON,OFF) Lights "Active Lights [%d]" // e.g. ON and "2"
Group:Switch:AND(ON,OFF) Lights "Active Lights [%d]" // e.g. ON and "2"
Group:Number:AVG Temperatures "All Room Temperatures [%.1f °C]" // e.g. "21.3 °C"
Group:DateTime:EARLIEST LatestUpdate "Latest Update [%1$tY.%1$tm.%1$tY %1$tH:%1$tM:%1$tS]"
Group:DateTime:LATEST LastSeen "Last Seen [%1$tY.%1$tm.%1$tY %1$tH:%1$tM:%1$tS]"
Group:String:COUNT("OFFLINE") OfflineDevices "Offline Devices [%d]" // e.g. "2"
```

The first two examples above compute the number of active lights and store them as group state.
However, the second group is of type switch and has an aggregation function of OR.
The first three examples above compute the number of active lights and store them as group state.
However, the second group is of type switch and has an aggregation function of `OR`.
This means that the state of the group will be `ON` as soon as any of the member lights are turned on.
The third uses `AND` and sets the Group state to `ON` if all of its members have the state `ON`, `OFF` if any of the Group members has a different state than `ON`.

Groups do not only aggregate information from individual member Items, they can also accept commands.
Sending a command to a Group causes the command to be sent to all Group members.
An example of this is shown by the second group above; sending a single `ON` or `OFF` command to that group turns all lights in the group on or off.

The third example computes the average temperature of all room temperature Items in the group.
The fourth example computes the average temperature of all room temperature Items in the group.

Assuming we have a Group containing three timestamps: `now().minusDays(10)`, `now()` and `now().plusSeconds(30)`.
The `EARLIEST` function returns `now().minusDays(10)`, the `LATEST` function returns `now().plusSeconds(30)`.

The last Group counts all members of it matching the given regular expression, here any character or state (simply counts all members).

{: #tags}
### Tags
Expand Down