Switching gears, you've asked a lot of implementation-specific questions. I'll answer what I can, but my answer for many of them is going to be that I'm not sure and that you should test things.
- Rejection granularity. If one endpoint declares an unsupported device type, does Home reject only that endpoint, or the entire accessory? If it is per-endpoint, I can declare 0x0042 natively and carry a compatibility endpoint alongside it.
I believe it will just ignore any endpoint it doesn't recognize. Keep in mind that this vendor-specific endpoints are also common in HAP, so this situation isn't actually all that unusual.
- Multiple device types on one endpoint. Can a single endpoint declare both 0x0042 (Water Valve) and 0x010A (On/Off Plug-in Unit) in its Descriptor DeviceTypeList, so certified firmware stays native and Home renders it via the type it recognises? Does Home pick the first supported type it finds, or reject the endpoint outright?
I don't know, this is something you'd need to test.
- Composition vs Bridge. Also not addressed: for a controller with seven independently controlled valves, does Apple prefer one accessory with seven endpoints, or a Bridge (0x000E) exposing seven accessories?
I think it depends entirely on the nature of your accessory and how it best integrates into the home. Conceptually, HomeKit considers an "accessory" to be the base "object" and a bridge is just a special type of accessory that "hands" the system multiple accessories at once, so the "default" expectation is that a given physical accessory will be implemented as a single accessory.
The main issue here is that accessories are assigned to individual rooms, so an accessory can only ever be in a single room. That is totally sensible for most accessories except that some thinking like large-scale irrigation or HVAC systems may not really "feel" right if all of its components are forced to be in the same room. For irrigation systems in particular, the HAP spec basically allows either approach based on the specifics of the hardware involved.
One final note here— while HomeKit itself uses "HMAccessory" as its central object, what Home.app actually presents are the "HMService" objects one level "below" the accessory. So the same accessory can show up multiple times in the same room, since it's presenting multiple services. However, if you shift one of those services to a different room, you'll find that both move.
Bridge is on your supported list, so does bridging change how Home treats child endpoints whose device types are not supported?
No.
- Re-reading composition
So, as full disclosure, I'm FAR more familiar with the HAP (HomeKit Accessory Protocol) spec than I am with Matter, so a lot of my guidance is based on my familiarity with how HomeKit and HAP interact, not Matter itself. I think this guidance will still be helpful/useful, but you'll need to do a certain amount of extrapolation and experimentation to sort out the details.
Let me start here:
And is there any state Home caches across a reboot that would keep showing a removed endpoint?
So, the first critical point here is that when you modify an accessory in Home.app, there’s no way to know whether the device is:
-
Directly sending a command to an accessory it's connected to.
-
Routing the command through a Home Hub it has "real time" access to.
-
The command is going through some longer/slower relay path that eventually reaches the accessory.
The key point here is that #2 and ESPECIALLY #3 aren't directly communicating with the accessory, so they can't actually know its current configuration.
Shifting to the hardware, within HAP, every accessory published a "configuration number" (c#) which was ONLY incremented when the accessory changed its logical configuration. Every time a controller connected to the accessory, HomeKit would first check that value and then "rescan" the accessory’s configuration, adjusting its configuration "as needed".
That dynamic is where this guidance comes from:
You suggested rebooting the accessory
HomeKit doesn't expect the configuration to change while it's actively connected to your accessory. Frankly, doing so is inherently somewhat "weird", as there's no good way for a controller to send a series of commands when the target of those commands could change at any time. So, if changing the configuration requires that no one be connected to the accessory, then the simplest way to guarantee that is to... reboot the accessory. You don't HAVE to do that, but what you DO have to do is close enough to a reboot... that it's almost always easier to just reboot.
is a change to the root Descriptor PartsList alone sufficient to trigger a re-scan on the next reconnect?
I'm not entirely sure what that matter equivalent to what is to what I've described above.
Device type IDs behind the categories. You have confirmed no authoritative list exists.
Actually, can you file a bug asking for this and post the number back here? I'd like to share something like this, and having a developer bug would help facilitate that.
Can you at least confirm the specific device type IDs behind "outlets", "switches”, and the five supported sensor types?
I think these are the values:
Outlets -> 0x010A, 0x010B
Switches -> 0x000F, 0x0103, 0x0104, 0x0105
Contact Sensor -> 0x0015
Light Sensor -> 0x0106
Occupancy Sensor -> 0x0107
Temperature Sensor -> 0x0302
Humidity Sensor -> 0x0307
So Home can already express valve semantics; the gap is specific to the Matter path.
So, the big issue here is that while the basic building blocks like "valve" are present, the higher level "Irrigation System" definitions are different enough that they can't be directly mapped to each other. That's different than the clusters HomeKit supports today, where the mapping is quite direct.
Is a HAP-based accessory or a HAP bridge the sanctioned way to get correct valve semantics today?
If you want to have full Home.app support "today”, then, yes, HAP is the only way to do that.
and is Matter parity with those existing HAP service types the intended direction?
Unfortunately, I can't talk about our future plans.
__
Kevin Elliott
DTS Engineer, CoreOS/Hardware
