Parent & Child Devices (grounded)

A Hubitat device can own other devices. The owner is a parent, the owned are children, and the set is one physical thing (or one cloud account) projected as several hub devices — a power strip's outlets, a Hue bridge's bulbs, a dual switch's two loads.

Sources: Hubitat's Parent/Child Drivers doc and its genericComponentParentDemo.groovy / genericComponentDimmer.groovy examples, plus the /hub2/devicesList tree verified live on 2.5.1.128 (C-8 Pro) against a hub of 151 top-level devices and one parent owning 5 children.

The parent is a device OR an app

• Parent device — a driver creates children for a multi-endpoint node: power strips with per-outlet control, dual switches/outlets, fan+light controllers. Children display indented under the parent in the Devices list.
• Parent app — an app creates the devices. Philips Hue Integration and Lutron Integrator work this way (each Hue bulb is a child of the integration app), as do CoCoHue and HubiThings Replica (rules/device-lifecycle.md). These are harder to see: the device is not indented anywhere, and its only tell is a "Parent app" row in the Device Details table on the device page's Device Info tab (/device/fullJson/<id> exposes it as parentApp — skills/_reference/endpoints.md).

Both make the device a child. Only the reporting differs.

Reading the tree — GET /hub2/devicesList

Returns {suggestBackup, devices:[...]}, and devices is a tree, not a flat list. Each entry is {key, data, children, parent, child}:

• key — DEV-<id>
• parent — bool: this device is a parent. It is not a pointer to one.
• child — bool: this device is a child.
• children[] — the owned entries, same shape, nested.

Children appear only nested — never at the top level. The grounded hub returns 151 top-level entries and 5 children reachable only by walking children[] (156 devices in all). Iterating devices[] without recursing silently misses every child device.

Verified child entry: parent:false, child:true, driver type Zooz Power Strip Outlet Component, DNI 1A-CH1…1A-CH5 under parent DNI 1A. Deriving a child DNI from the parent's is the common pattern, not a requirement — the docs state authors may use any convention, and Hubitat's own example keys on the parent's device.id instead ("${device.id}-${type}").

data.source is System | User | Linked. Linked marks a hub-mesh device owned by another hub — orthogonal to parent/child (2 on the grounded hub).

Why it bites

• A child has no radio of its own. The parent holds the node and fans commands out, so there is nothing to exclude or repair at the radio level for a child (rules/zwave-zigbee-mesh.md).
• Delete the parent and the children go with it. /device/fullJson/<id> lists child devices, so the removal blast radius includes them (rules/device-lifecycle.md).
• Children are excluded from Settings → Swap Device. Verified on 2.5.1.128: all 151 top-level devices were offered, all 5 children absent. The page states it — "Most child devices are not swappable and are not listed here. Attempting to swap them will break related integrations." ("Most": AirPlay, Bluetooth, HomeKit Controller, Tuya, and Wiz are allowed as exceptions.) The live check covered device-parented children; app-parented exclusion is the doc's claim, untested here. See skills/device-migration/SKILL.md.
• Re-adding a parent mints new child ids, stranding every reference — the same trap as any replacement.

state.endPoints > 0 is not proof the children exist

On a multi-endpoint Z-Wave device, state.endPoints records what the device reported, not what the hub created. Check fullJson.hasChildren / childDevices for existence, never state.endPoints — the same "children are invisible to the flat list" family as the tree read above.

A platform update can start surfacing that gap as a stream of device errors on a device that has been fine for a month. Grounded 2026-08-12: a Zooz ZEN14 outdoor double plug began erroring No device for endpoint (1)/(2). Press Configure to create child devices. on the first refresh after the hub updated to 2.5.1.152. Every error forwarded to notifications, so it read as a device fault. It was not — the device had carried state.endPoints = 2 for a month while refresh() sent a per-endpoint switchBinaryGet every 6 h with no errors, and the parent's on()/off() targets endpoint 0 and drives both outlets, which is what Alexa, HomeKit and Maker API all use. Nothing was broken before or after.

The errors fire only on an inbound report carrying a non-zero endpoint, so the endpoint-encapsulated replies had previously not been reaching the driver with their endpoint. (The dispatch mechanism is inference from a tight correlation across the restart, not measured.)

The trap for anyone diagnosing it. Reading the driver, you would conclude Configure cannot help: createChildDevices() is called only from the MultiChannelEndPointReport handler, and the probe that requests that report fires only when state.endPoints == null — which it isn't. Configure works anyway, because configure() → clearVariables() → state.clear() nulls endPoints, so the probe re-fires. That indirection is the whole answer and it is invisible from the two obvious call sites.

Two notes for the repair:

• Configure also forces a full parameter resync. Compare fullJson.settings[].defaultValue against device.data.configVals first — on the grounded device all eight matched, so the resync was a no-op.
• Children are named from device.name (the driver type), not the device label, so they land as <Driver Type> - Outlet N and need relabelling.

A scan for other exposed devices only sees drivers that track endpoints in state, so it is not conclusive for built-in drivers.

Writing a parent/child pair

• Create from an app or a driver: addChildDevice(namespace, typeName, deviceNetworkId, properties). Hubitat's example: addChildDevice("hubitat", "Generic Component Switch", "${device.id}-Switch", [name: "...", isComponent: true]). Built-in component drivers use namespace hubitat; a custom child driver uses its own.
• Prefer the built-in "Generic Component …" drivers when one matches your capabilities — fewer custom drivers for users to install.
• Commands travel child → parent: the child's Xyz() calls componentXyz(cd) on the parent, passing the child device as the first parameter (componentOn(cd), componentSetLevel(cd, level, transitionTime)). The parent does all the Z-Wave/Zigbee/Matter/LAN talking.
• Events travel parent → child: the parent calls parse() on the child with a List of Event maps — getChildDevice(cd.deviceNetworkId).parse([[name:"switch", value:"on", descriptionText:"..."]]). Component drivers turn those into events. This is the convention, not sendEvent on the parent (rules/state-vs-attributes.md).
• Address children with getChildDevice(dni) / getChildDevices().
• Parent/child is the only way two devices see each other. Two ordinary devices on the hub cannot call each other at all; a parent may call any method on its child (including reading attributes), and the child any method on the parent. A parent app likewise gets full method access, unlike an app holding a device from an input (rules/app-lifecycle.md).