XBOS Interface Development

[gtfierro]

Document an initial set of standard interfaces for device and service drivers

An initial set of interfaces to develop:

• [x] Thermostat
• [ ] Sensor
• [x] Plug load
• [x] Electric Meter
• [x] Lighting
• [x] EVSE

[gtfierro]

Begun in https://docs.xbos.io/driver_interfaces.html

[gtfierro]

We may want to change names to include the xbos name, e.g. i.thermostat -> i.xbos.thermostat

The additional namespacing would reduce ambiguity

[immesys]

No idea what just happened

[immesys]

So. Was going to say. Do you have objections to specifying the units in the interfaces? I would prefer SI units, but any fixed units would be preferable to none

[gtfierro]

The units in the interface name, e.g. i.xbos.thermostat, or units in the name of the slot/signal, e.g. temperature.f?

If an interface name has many types in its exposed signals/slots (e.g. thermostat would have temperature, humidity, HVAC state), how would we include that all in the interface name?

Or, more concretely, what would that look like for the Venstar bulk-struct?

Message from somewhere/devices/venstar/s.venstar/mytstat/i.venstar/signal/info:
PO 2.0.9.16 len 371 (msgpack) contents:
{
  "UUID": "07317ac4-694e-3f79-bf5e-ed58e50e9291",
  "availablemodes": 2,
  "away": 0,
  "cooltemp": 93,
  "cooltempmax": 99,
  "cooltempmin": 35,
  "fan": 0,
  "fanstate": 1,
  "forceunocc": 0,
  "heattemp": 76,
  "heattempmax": 99,
  "heattempmin": 35,
  "holiday": 0,
  "mode": 3,
  "name": "mytstat",
  "override": 0,
  "overridetime": 0,
  "schedule": 1,
  "schedulepart": 1,
  "setpointdelta": 2,
  "spacetemp": 74,
  "state": 1,
  "tempunits": 0,
  "time": 1487377263230172592
}

[immesys]

No I mean in the definition of the interface, not in the names

[gtfierro]

Oh, so the definition of the interface itself would include that information, rather than it being in-band?

I could see that working; obvious next question is if there are any other timeseries tags that would need to be applied at the terminals, but couldn't also be solved in the same way. This is an issue if you see a device that publishes

{
    MTU1: 123, // volts
    MTU2: 456 // volts
    .....
    MTU100: ....
}

and you want to label the origins of MTU1,MTU2, etc separately

[gtfierro]

@jhkolb @immesys Initial versions of some basic XBOS interfaces have been added to https://github.com/SoftwareDefinedBuildings/XBOS/tree/master/interfaces . Please review when you have a chance?

[jhkolb]

Looks like a good start!

Maybe I'm missing something, but is the plan to define only monitoring interfaces for now? What about actuation?

[gtfierro]

For now, yes, as that's the most immediate task, but its worth discussing here too

There are a couple of related outstanding issues:

• currently the interface definitions assume a single "output" signal (probably called info or state or something like that). Is this okay? What's the principle for dividing an interface among multiple signals?
• for actuation/input, do we want to have a single slot that takes a kv-pair of field: value, or do we have a separate slot for each actuation signal? I like the latter, because we can apply permissions more finely

Thoughts?

[jhkolb]

The discussion at this week's meeting would imply that we publish status information under one large struct, right? Publishing to a state signal seems logical then.

I also like the idea of having a separate slot for different actuation commands because of the implications for permissions, although this is now asymmetric with our approach to signals.

[gtfierro]

Yes, I think we've decided that we're going to have drivers publish structs (under a single signal in our current interface versions).

Regarding the asymmetry, I think we could make the case that we will more likely want to limit the kinds of actuations performed than the data collected. It doesn't make a whole lot of sense to grant access to consume the temperature of the thermostat but not its setpoint (or alternatively the state of a light but not its brightness). Splitting the state publishing on interfaces or instantiations of interfaces forces a slightly coarser permissions structure, but I think this makes it more manageable.

However, it may be the case that we want to allow actuation of heating/cooling setpoints, but not allow direct actuation of the thermostat's HVAC state (whether its calling for heat/cool)

[gtfierro]

Okay I took a stab at doing this interface decomposition with some examples where we have multiple different slots with different levels of granularity (e.g. a "setpoints" slot for a thermostat vs a "full" actuation slot)

https://github.com/SoftwareDefinedBuildings/XBOS/blob/master/interfaces/xbos_thermostat.yaml

Its not 100% swagger compliant, but we're getting at a different flavor of interfaces anyway, so I think that's alright.