RFC: Add an ItemStateUpdatedEvent

[J-N-K]

Follow-Up To #1092, #1093, #2286

There has been quite some confusion about the ItemStateEvent which is not emitted by the item if the state was updated but by an "external" source to update the item's state. Since these external sources do not necessarily know about the item type (e.g. a switch in the UI is agnostic of the item being Color, Dimmer or Switch and will send ON or OFF) or the unit of the item, the state in the ItemStateEvent does not reflect the new item's state.

It seems that there are use cases for an event that is emitted if the state was updated and what the new state is (similar to the ItemStateChangedEvent).

[J-N-K]

@spacemanspiff2007 I would appreciate if you could shortly describe what the use-case for the ItemStateUpdated/GroupStateUpdated event is.

[spacemanspiff2007]

Thank you @J-N-K for consolidating the issues.

When consuming the events I need an event on which I can set the locally cached item state accordingly.
Originally I thought that the ItemStateEvent is exactly that event since the name indicates that a new item state has been set.
This led to the following understanding:

sequenceDiagram
    participant openHAB
    participant device
    participant sse listener

openHAB->>+device: command
openHAB->>sse listener: ItemCommandEvent
device->>-openHAB: report state

loop
    openHAB->>openHAB: Set item state
end

openHAB->>sse listener: ItemStateEvent
openHAB->>sse listener: ItemStateChangedEvent (optional)

Loading

However it's very confusing that the ItemStateEvent data does not match the data from ItemStateChangedEvent.
I had to implement the logic myself that transforms the values to the corresponding item values:
e.g. ON to 100% brightness or 30,100,100 in case of a HSB value.

I can not use the ItemStateChangedEvent to set the value because the ItemStateEvent comes before it and many users trigger their rules on the ItemStateEvent. This would lead to the case where e.g. the ItemStateEvent signals "ON" but the HABApp internal item state is still OFF because the ItemStateChangedEvent comes after the ItemStateEvent.

---

I hope the example makes it clear that there is the need for an event which contains the current, updated item state.
This event has to be emitted before the ItemStateChangedEvent! It could then have the UOM set as an additional field, too so I don't have to split the value on the last white space.
Imho it's good if the API is consistent so this new event should be sent for item groups, too.

---

Since the ItemStateEvent contains the update information used internally by openHAB I would propose to not expose these events over the API. Since removing things is always hard how about just logging a message when an event listener connects that listens to the ItemStateEvents that there is a new event available that should be used instead. Then after an arbitrary time frame the ItemStateEvent can be removed.

[spacemanspiff2007]

Other useful things that this event could implement:

• Separation of State and UoM. UoM then should be accessible through extra field
• Timestamp when the Item updated the state

[openhab-bot]

This issue has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/openhab-4-0-wishlist/142388/449