Alarm Capability Schema

[cr0ybot]

Several devices may have some kind of alarm/alert that could be critical to the safety of a building's occupants. This includes smoke alarms, CO detectors, alarm systems, and possibly door/window locks and other security-related devices. Perhaps there is room in the schema for an AlarmProperty or AlarmEvent, in conjunction with an Alarm Capability, to denote devices with high-priority notifications.

As an example, I'm working on interfacing with a Nest Protect, smoke/CO detector. It has separate interfaces for the smoke alarm status and CO alarm status, both of which have 3 states: ok, warning, and emergency.

[benfrancis]

An AlarmCapability seems like a good idea.

It might be good to look at more implementations to help inform the structure of the schema.

We could have an AlarmEvent with an enum constrained text string distinguishing between different alerts. There may also be use cases for queryable properties.

[jaller94]

Are there more specific words for a critical, alert-type alarm vs an alarm (clock)? Before I opened the ticket – still thinking of what I what to automate in my home – I was thinking of an alarm clock. ⏰

[benfrancis]

Are there more specific words for a critical, alert-type alarm vs an alarm (clock)?

An alarm clock seems like a valid use of an Alarm capability.

You can always combine it with other capabilities to add other features.

[benfrancis]

Here's a proposed example of a complex alarm device which has a smoke sensor, CO sensor, temperature sensor, audible alarm and light. Note that the SmokeProperty and AlarmProperty are separate properties. The former reports whether smoke has been detected and the latter reports whether the audible alarm is currently sounding - these properties may be monitored/controlled separately.

{
  "@context": "https://iot.mozilla.org/schemas/",
  "@type": ["SmokeAlarm", "SmokeSensor", "CarbonMonoxideSensor", "TemperatureSensor", "Alarm", "Light"],
  "name": "Smoke Alarm",
  "description": "Detects smoke",
  "properties": {
    "smoke": {
      "@type": "SmokeProperty",
      "type": "boolean",
      "title": "Smoke",
      "description": "True when smoke detected",
    },
    "co": {
      "@type": "CarbonMonoxideProperty",
      "type": "number",
      "title": "CO",
      "description": "Current carbon monoxide concentration",
      "unit": "parts per million"
    },
    "temperature": {
      "@type": "TemperatureProperty",
      "type": "number",
      "title": "Temperature",
      "description": "Current temperature",
      "unit": "degree celcius"
    },
    "alarm": {
      "@type": "AlarmProperty",
      "type": "boolean",
      "title": "Alarm",
      "description": "True when alarm is sounding"
    },
    "light": {
      "@type": "OnOffProperty",
      "type": "boolean",
      "title": "Light",
      "description": "LED lamp"
    }
  },
  "events": {
    "@type: "AlarmEvent",
    "type": "string"
  }
}

I'm thinking about an Alarm capability which has an AlarmProperty and AlarmEvent, a SmokeSensor capability which has a SmokeProperty and perhaps a SmokeAlarm capability which has all three.

Rather than boolean, AlarmProperty could be a string with an enum (e.g. ["ok", "warning", "emergency"] to represent multiple levels of alarm (which could have different audible alerts for example). The AlarmEvent could also have an enum.

What do you think?

[mrstegeman]

1. I like the idea of SmokeSensor and SmokeProperty, but I think SmokeAlarm is probably redundant.
2. Can we also go ahead and create the CO sensor and property schemas? Note that in HomeKit, the CO property is a boolean (CO detected), rather than a number.
3. I think an enum is probably better for the alarm. I'm fine with the 3 states, assuming that ok means "no alarm".
4. Will AlarmEvent be required? And yes, it should probably include the same enum.