Refine UnDefType usage

[ccutrer]

• NULL means absence of state
• UNDEF means having a state that cannot be represented

[seime]

I'm not so certain about this one, the documentation is ambigous, and looking at other official bindings it is a mix of NULL and UNDEF. So I asked ChatGPT for it's understanding of this:

---

Good question — in openHAB, the difference between NULL and UNDEF can be subtle but important. Here’s a clear breakdown:

---

🔹 NULL

• Means the Item has never been initialized.
• It’s the default state for an Item before it has ever received a value.
• Typical scenario: You just defined a new Item, but no binding or rule has given it a value yet.
• Example: A temperature sensor Item that’s never reported any reading.

---

🔹 UNDEF

• Means the Item is in an undefined state due to an error or lack of valid data.
• The Item has been initialized before, but the binding or logic cannot provide a meaningful value at the moment.
• Typical scenario: A binding cannot read from a device due to a communication error, or the device sends invalid data.
• Example: A zwave door sensor lost connection; the binding reports UNDEF.

---

✅ When it matters:

• Rules: You often check for NULL or UNDEF to handle missing or invalid data gracefully.

  if (MyItem.state == NULL) {
      logInfo("Example", "Item never initialized")
  } else if (MyItem.state == UNDEF) {
      logInfo("Example", "Item cannot provide a valid value")
  }

• Sitemaps/UIs: You might want to hide or replace NULL/UNDEF with a placeholder to avoid confusing values.

---

Tip:
NULL means “I don’t know anything yet”, UNDEF means “I knew something before, but I can’t provide it now”.

---

I made a very rough search for usage of UndefType.NULL vs UndefType.UNDEF in openhab-addons, and https://github.com/search?q=repo%3Aopenhab%2Fopenhab-addons+UndefType.NULL&type=code reported 185 files while https://github.com/search?q=repo%3Aopenhab%2Fopenhab-addons+UndefType.UNDEF&type=code reported 450 files

In general I think OH should clarify what's actually supposed to be used, and also update it's official bindings accordingly.

[ccutrer]

Yes, I agree the docs are lacking. I had previously been told to do it this way in a PR to the official repo. But it's not super important to me; I can back-burner it for now unless/until we can get clarification from core.