package com.codename1.home

A cross-platform smart-home API: read the home’s accessories, read and write what they can do, watch them for change, run scenes, and add new Matter accessories.

SmartHome.getInstance() is the single entry point and never returns null. Ports without smart-home support return a fallback whose operations fail fast with HomeError.NOT_SUPPORTED and whose graph accessors return empty lists, so calling code needs no platform-specific if.

The model

A HomeStructure holds HomeRooms and Accessorys. An accessory has one or more AccessoryServices – a two-gang wall switch is one accessory with two services – and a service exposes Traits. A trait is a canonical capability, not a platform identifier: Trait.BRIGHTNESS is the same constant whether the accessory is behind HomeKit or Matter, and the port maps it to HMCharacteristicTypeBrightness or Level Control’s CurrentLevel on your behalf.

Graph objects are immutable snapshots. Nothing on an Accessory crosses into the platform when you call a getter; when the topology moves, a HomeStructureListener tells you to fetch it again.

Three things that will surprise you

Android’s default answer is not “available”. With no extra setup an Android app can commission a Matter accessory into the user’s Google Home and can do nothing else – the graph is empty and no trait can be read or written. That state is HomeAvailability.COMMISSIONING_ONLY, and it is reported honestly rather than dressed up as a working home. The full accessory graph on Android needs the Google Home APIs, which need a Google Cloud project and a Home Developer Console registration that only you can create. See SmartHome.getConfigurationProblems().

Nothing wakes your app for an accessory change. HomeKit delivers changes only while your app is running in the foreground, and the Google Home APIs need a live signed-in client. The home hub, not your app, is what runs automations while the phone sleeps. Ask TraitSubscription.isPushDelivery() rather than assuming; where it answers false, changes arrive when you call SmartHome.drainChanges() and at no other time.

Commissioning may not give you a device you can control. Adding an accessory through Google Play services puts it in the user’s Google Home and tells your app nothing more. Check CommissioningResult.wasCommissionedToThisApp() instead of assuming the returned accessory id is usable.

Threading

Every method may be called from the EDT and returns immediately. Every result and every listener delivery arrives on the EDT, on every platform – including the desktop, simulator and JavaScript ports, which marshal rather than answering on whichever thread happened to ask. A callback may touch components directly.

Not claimed in this release

Automations, triggers and conditions (scenes only); topology writes (creating homes, renaming rooms, moving accessories); cameras and video; security and alarm panels; Matter events, which is why LockState.JAMMED is unreachable outside HomeKit; energy, appliance and diagnostic clusters. Codename One is not a Matter controller: everything Matter goes through the OS ecosystem, so the Apple Home or Google Home app has to be installed and set up.

Types

`class Accessory`	One physical device in the home: HomeKit’s `HMAccessory`, a Google Home device, one Matter node.
`enum AccessoryCategory`	Roughly what an `Accessory` is, for picking an icon and grouping a list.
`class AccessoryService`	One functional endpoint of an `Accessory`: HomeKit’s `HMService`, one Matter endpoint.
`enum AirQualityLevel`	A summarized air-quality rating, for `Trait.AIR_QUALITY`.
`enum AlarmState`	The state of a life-safety alarm, for `Trait.SMOKE_DETECTED` and `Trait.CO_DETECTED`.
`enum ChargingState`	Whether an accessory’s battery is charging, for `Trait.BATTERY_CHARGING`.
`enum DoorState`	The state of a door or garage door, for `Trait.DOOR_STATE` and `Trait.TARGET_DOOR_STATE`.
`enum FanMode`	How a fan is running, for `Trait.FAN_MODE`.
`enum HeatingCoolingMode`	What a thermostat is doing, for `Trait.CURRENT_HEATING_COOLING`, or what it has been asked to do, for `Trait.TARGET_HEATING_COOLING`.
`enum HomeAuthorizationStatus`	Whether the user has granted this app access to their home.
`enum HomeAvailability`	Whether a home graph is usable right now, and when it is not, why.
`enum HomeBackend`	Which platform service is behind this `SmartHome` instance.
`interface HomeChangeListener`	Told when a watched `Trait` changes value.
`class HomeConfigurationException`	Raised when the app itself is missing something the backend needs – an entitlement, a build hint, a Google Cloud project id – rather than the user or the device being at fault.
`enum HomeError`	Typed failure reasons carried by `HomeException`.
`class HomeException`	The failure delivered through an `AsyncResource` when a smart-home operation does not succeed.
`class HomeRoom`	A room in a `HomeStructure`: HomeKit’s `HMRoom`, a Google Home room.
`class HomeStructure`	One home: HomeKit’s `HMHome`, a Google Home structure.
`class HomeStructureEvent`	Notification that the home graph moved, delivered to a `HomeStructureListener` on the EDT.
`interface HomeStructureListener`	Told when the home graph moves – an accessory added, removed, renamed, moved between rooms, or its reachability changing.
`class HomeZone`	A named grouping of rooms – “upstairs”, “the annexe”: HomeKit’s `HMZone`.
`enum LockState`	The state of a door lock, for `Trait.LOCK_STATE` and `Trait.TARGET_LOCK_STATE`.
`enum PositionState`	Which way a window covering is moving, for `Trait.COVERING_MOTION`.
`class Scene`	A named set of accessory states that can be applied in one go: HomeKit’s `HMActionSet`, a Google Home scene.
`class SceneAction`	One thing a `Scene` does: set one `Trait` on one `AccessoryService` to one value.
`enum SceneType`	What kind of `Scene` this is.
`enum ServiceType`	What one `AccessoryService` is: HomeKit’s `HMService` type, Matter’s device type on an endpoint.
`class SmartHome`	Entry point for the Codename One smart-home API – reading the accessories in a user’s home, reading and writing what they can do, watching them for change, running scenes, and adding new Matter accessories.
`enum StructureChangeKind`	What moved in the home, for `HomeStructureEvent`.
`class SubscriptionRequest`	Which traits to watch, and how often you are willing to hear about them.
`class Trait`	One capability an accessory can have: a light’s brightness, a lock’s state, a sensor’s reading.
`class TraitChangeBatch`	A coalesced set of trait changes, delivered to a `HomeChangeListener` on the EDT.
`class TraitConstraint`	What one particular accessory will actually accept for one particular `Trait`: whether it can be read or written, the range it works over, the step it moves in, and for an enum trait, which constants it can produce.
`class TraitReadRequest`	Which traits to read, and how fresh they have to be.
`class TraitReading`	One trait’s value at one moment, or the reason there isn’t one.
`class TraitSubscription`	A live watch on a set of traits, returned by `SmartHome.subscribe(SubscriptionRequest, HomeChangeListener)`.
`enum TraitUnit`	A unit of measure for a `Trait` value.
`enum TraitUnitDimension`	What a `TraitUnit` measures.
`class TraitValue`	One value of one `Trait`: immutable, typed, and carrying its unit.
`enum TraitValueKind`	What sort of value a `Trait` carries, and therefore which `TraitValue` getter is the one that works.
`class TraitWrite`	One change to make: set one `Trait` on one `AccessoryService` to one value.
`class TraitWriteResult`	What happened to one `TraitWrite`.