# Package com.codename1.home

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 `HomeRoom`s and `Accessory`s. An accessory has one or more `AccessoryService`s -- a two-gang wall switch is one accessory with two services -- and a service exposes `Trait`s. 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.

- Related Packages
  Package
  Description
  com.codename1.home.commissioning
  Adding a new Matter accessory to the user's home.
  com.codename1.home.spi
  The service-provider interface each platform port implements to back `SmartHome`.
- Class
  Description
  Accessory
  One physical device in the home: HomeKit's `HMAccessory`, a Google Home device, one Matter node.
  AccessoryCategory
  Roughly what an `Accessory` is, for picking an icon and grouping a list.
  AccessoryService
  One functional endpoint of an `Accessory`: HomeKit's `HMService`, one Matter endpoint.
  AirQualityLevel
  A summarized air-quality rating, for `Trait.AIR_QUALITY`.
  AlarmState
  The state of a life-safety alarm, for `Trait.SMOKE_DETECTED` and `Trait.CO_DETECTED`.
  ChargingState
  Whether an accessory's battery is charging, for `Trait.BATTERY_CHARGING`.
  DoorState
  The state of a door or garage door, for `Trait.DOOR_STATE` and `Trait.TARGET_DOOR_STATE`.
  FanMode
  How a fan is running, for `Trait.FAN_MODE`.
  HeatingCoolingMode
  What a thermostat is doing, for `Trait.CURRENT_HEATING_COOLING`, or what it has been asked to do, for `Trait.TARGET_HEATING_COOLING`.
  HomeAuthorizationStatus
  Whether the user has granted this app access to their home.
  HomeAvailability
  Whether a home graph is usable right now, and when it is not, why.
  HomeBackend
  Which platform service is behind this `SmartHome` instance.
  HomeChangeListener
  Told when a watched `Trait` changes value.
  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.
  HomeError
  Typed failure reasons carried by `HomeException`.
  HomeException
  The failure delivered through an `AsyncResource` when a smart-home operation does not succeed.
  HomeRoom
  A room in a `HomeStructure`: HomeKit's `HMRoom`, a Google Home room.
  HomeStructure
  One home: HomeKit's `HMHome`, a Google Home structure.
  HomeStructureEvent
  Notification that the home graph moved, delivered to a `HomeStructureListener` on the EDT.
  HomeStructureListener
  Told when the home graph moves -- an accessory added, removed, renamed, moved between rooms, or its reachability changing.
  HomeZone
  A named grouping of rooms -- "upstairs", "the annexe": HomeKit's `HMZone`.
  LockState
  The state of a door lock, for `Trait.LOCK_STATE` and `Trait.TARGET_LOCK_STATE`.
  PositionState
  Which way a window covering is moving, for `Trait.COVERING_MOTION`.
  Scene
  A named set of accessory states that can be applied in one go: HomeKit's `HMActionSet`, a Google Home scene.
  SceneAction
  One thing a `Scene` does: set one `Trait` on one `AccessoryService` to one value.
  SceneType
  What kind of `Scene` this is.
  ServiceType
  What one `AccessoryService` is: HomeKit's `HMService` type, Matter's device type on an endpoint.
  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.
  StructureChangeKind
  What moved in the home, for `HomeStructureEvent`.
  SubscriptionRequest
  Which traits to watch, and how often you are willing to hear about them.
  Trait
  One capability an accessory can have: a light's brightness, a lock's state, a sensor's reading.
  TraitChangeBatch
  A coalesced set of trait changes, delivered to a `HomeChangeListener` on the EDT.
  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.
  TraitReading
  One trait's value at one moment, or the reason there isn't one.
  TraitReadRequest
  Which traits to read, and how fresh they have to be.
  TraitSubscription
  A live watch on a set of traits, returned by `SmartHome.subscribe(SubscriptionRequest, HomeChangeListener)`.
  TraitUnit
  A unit of measure for a `Trait` value.
  TraitUnitDimension
  What a `TraitUnit` measures.
  TraitValue
  One value of one `Trait`: immutable, typed, and carrying its unit.
  TraitValueKind
  What sort of value a `Trait` carries, and therefore which `TraitValue` getter is the one that works.
  TraitWrite
  One change to make: set one `Trait` on one `AccessoryService` to one value.
  TraitWriteResult
  What happened to one `TraitWrite`.