public final class Trait

Whether the accessory is on.

HomeKit spells this two ways – PowerState on a lightbulb or switch, and Active on a fan v2, air purifier or heater-cooler – and this one constant covers both; the port uses whichever characteristic the service actually has. Two traits here would be a HomeKit implementation detail leaking into portable code.

Matter: On/Off cluster 0x0006, OnOff attribute.

Note that on Matter this is genuinely independent of BRIGHTNESS: level 0 does not reliably mean off, and turning a light off does not zero its level. Write this trait to turn something off.

Whether something is plugged into an outlet and drawing power.

HomeKit: OutletInUse.

Absent on Matter and Google Home. Matter’s Electrical Power Measurement cluster answers a different question – how much current is flowing – and it is optional and rare besides. A lamp that is plugged in but switched off draws nothing, so deriving this from power draw would report an empty socket. The port answers HomeError.TRAIT_NOT_SUPPORTED rather than guessing.

How bright a light is, as a percentage.

HomeKit: Brightness, already a percentage.

Matter: Level Control 0x0008, CurrentLevel, which runs 1 to 254 with the real bounds in MinLevel and MaxLevel; written through MoveToLevel. 254 steps do not divide into 100, so setting 33 percent and reading it back can answer 33 or something adjacent. Do not compare a read against a value you wrote.

The hue of a colour light, in degrees around the colour wheel.

HomeKit: Hue, already in arcdegrees.

Matter: Color Control 0x0300, CurrentHue – a single byte covering the whole circle, so about 1.4 degrees per step. Where the accessory supports the enhanced-hue feature the port reads EnhancedCurrentHue instead and the resolution is much better.

A Matter light in XY or colour-temperature mode reports a stale hue. The port checks ColorMode and reports no value rather than passing on a number that does not describe the light you are looking at.

How saturated a colour light is, as a percentage.

HomeKit: Saturation. Matter: Color Control 0x0300, CurrentSaturation, 0 to 254. Same quantization and the same colour-mode caveat as HUE.

The colour temperature of a white light, in mireds.

HomeKit: ColorTemperature. Matter: Color Control 0x0300, ColorTemperatureMireds, bounded by the accessory’s own ColorTempPhysicalMinMireds and ColorTempPhysicalMaxMireds, which arrive on the TraitConstraint.

Mireds because that is what both platforms use natively, so nothing is converted on the way through. And the trap that catches everyone once: a higher mired value is a warmer light. 153 is a cold blue-white and 400 is candlelight. Use TraitValue.getColorTemperatureKelvin() if you would rather think in Kelvin.

Ambient light, in lux.

HomeKit: CurrentLightLevel, already in lux.

Matter: Illuminance Measurement 0x0400, MeasuredValue, which is logarithmically encoded as 10000 * log10(lux) + 1 in a single 16-bit field – so precision falls away sharply at the bright end. Its two sentinels, 0 for “too dark to measure” and 0xFFFF for “unknown”, become no value rather than a reading of zero lux.

The temperature an accessory is measuring.

HomeKit: CurrentTemperature on a sensor, or the thermostat’s own.

Matter: Temperature Measurement 0x0402 MeasuredValue for a sensor, or Thermostat 0x0201 LocalTemperature for a thermostat. Both are hundredths of a degree with 0x8000 meaning null, which becomes no value.

The single setpoint that applies in the thermostat’s current mode.

The largest structural mismatch in this table

HomeKit has one TargetTemperature characteristic. Matter has no such thing – it has OccupiedHeatingSetpoint and OccupiedCoolingSetpoint and nothing that unifies them.

So this trait is defined as the setpoint that applies right now: when TARGET_HEATING_COOLING is HeatingCoolingMode.HEAT it is the heating setpoint, when it is HeatingCoolingMode.COOL it is the cooling one, and when the mode is HeatingCoolingMode.AUTO this trait reports no value on either backend. In auto there are two setpoints and answering with either one would silently be the wrong one half the time; use TARGET_HEATING_TEMPERATURE and TARGET_COOLING_TEMPERATURE, which always mean exactly what they say.

A thermostat UI that only ever offers one number will be wrong on an auto-mode thermostat no matter what this API does. Offer two.

The temperature below which heating runs.

HomeKit: HeatingThreshold. Matter: Thermostat 0x0201, OccupiedHeatingSetpoint. Clean on both sides.

The temperature above which cooling runs.

HomeKit: CoolingThreshold. Matter: Thermostat 0x0201, OccupiedCoolingSetpoint. Clean on both sides.

What the thermostat is doing right now, as a HeatingCoolingMode.

HomeKit: CurrentHeatingCooling. Matter: Thermostat 0x0201, ThermostatRunningMode where the accessory has it, falling back to SystemMode.

Never HeatingCoolingMode.AUTO: at any instant a thermostat is heating, cooling or idle. Auto is a policy, and it lives on TARGET_HEATING_COOLING.

What the thermostat has been asked to do, as a HeatingCoolingMode.

HomeKit: TargetHeatingCooling, four values. Matter: Thermostat 0x0201, SystemMode, nine.

The five Matter modes HomeKit cannot express – emergency heat, precooling, fan-only, dry and sleep – arrive as HeatingCoolingMode.OTHER with the platform’s own ordinal on TraitValue.getRawPlatformValue(), rather than being flattened into HeatingCoolingMode.OFF. Writing OTHER is refused.

The relative humidity an accessory is measuring, as a percentage.

HomeKit: CurrentRelativeHumidity. Matter: Relative Humidity Measurement 0x0405, MeasuredValue, in hundredths of a percent with 0xFFFF meaning null.

The relative humidity a humidifier or dehumidifier is aiming for.

HomeKit: TargetRelativeHumidity.

Absent on Matter and Google Home. There is no standard target-humidity cluster in the Matter revisions the shipping ecosystems support, so the port answers HomeError.TRAIT_NOT_SUPPORTED.

What a door lock is doing, as a LockState.

HomeKit: CurrentLockMechanismState. Matter: Door Lock 0x0101, LockState, which is nullable and whose null becomes no value.

Note LockState.JAMMED is unreachable outside HomeKit and LockState.PARTIALLY_LOCKED is unreachable on HomeKit; the enum explains both.

Lock or unlock a door lock. Only LockState.SECURED and LockState.UNSECURED may be written.

HomeKit: TargetLockMechanismState, an ordinary characteristic write.

Matter has no such attribute – locking is the LockDoor command and unlocking is UnlockDoor on Door Lock 0x0101. That difference is invisible from here by design, with one exception that is not: a Matter lock configured with RequirePINforRemoteOperation will refuse an unlock without a credential and the write fails with HomeError.PIN_REQUIRED. Supply one through TraitWrite.setAuthorizationData(java.lang.String). HomeKit never takes a PIN and ignores the field.

What a door or garage door is doing, as a DoorState.

HomeKit: CurrentDoorState. Google Home: its own garage-door trait. Matter has no standard garage cluster, so this is unavailable on an Android build limited to HomeAvailability.COMMISSIONING_ONLY.

Open or close a door. Only DoorState.OPEN and DoorState.CLOSED may be written.

HomeKit: TargetDoorState. Same backend availability as DOOR_STATE.

Whether something is blocking a door or covering.

HomeKit: ObstructionDetected, on both doors and coverings.

Matter: the obstacle bit of Window Covering 0x0102 SafetyStatus – coverings only, since there is no garage cluster to carry it.

How far open a blind or shade is. 100 is fully open, 0 is fully closed.

The inversion to watch

This is the likeliest source of a shipped bug in the whole package. HomeKit’s CurrentPosition runs the way this constant does – 100 is open. Matter’s CurrentPositionLiftPercent100ths runs the other way, where 0 is fully open, and it is in hundredths of a percent besides, so the raw numbers differ by both a flip and a factor of a hundred.

This API takes the HomeKit convention because it is what a slider labelled “open” wants, and the Android bridge inverts. Nothing in application code should ever see Matter’s polarity – but if you are reading a Matter trace next to a Codename One log, that is why the two disagree.

Move a blind or shade. 100 is fully open, matching COVERING_POSITION; read that constant’s note.

HomeKit: TargetPosition. Matter: TargetPositionLiftPercent100ths to read back what was asked for, and the GoToLiftPercentage command to write.

How far the slats of a blind are tilted, as a percentage.

HomeKit models tilt as two characteristics in arcdegrees, CurrentHorizontalTilt and CurrentVerticalTilt, running -90 to 90. Matter models it as one percentage, CurrentPositionTiltPercent100ths.

This API takes Matter’s single-axis percentage. On iOS the port uses whichever axis the service exposes and maps the accessory’s real degree range onto 0 to 100, publishing the degrees on the TraitConstraint so a UI can still label them. Two-axis tilt is not supported: an accessory offering both gets its horizontal axis, and there is no way to reach the other one from portable code.

Tilt the slats of a blind. Same single-axis model as COVERING_TILT; read that constant’s note.

HomeKit: TargetHorizontalTilt or TargetVerticalTilt. Matter: TargetPositionTiltPercent100ths and the GoToTiltPercentage command.

Which way a covering is moving, as a PositionState.

HomeKit: PositionState. Matter: the global bits of Window Covering 0x0102 OperationalStatus.

Reported in terms of opening and closing, not of the position number rising or falling, because the two backends disagree about which direction that number runs.

Whether motion is being detected.

HomeKit: MotionDetected, a characteristic of its own.

Matter has no motion cluster. A Matter motion sensor is the Occupancy Sensor device type with a PIR sensor type, so on Matter and Google Home this trait and OCCUPANCY_DETECTED read the same bit and always agree.

Both are exposed anyway, rather than hiding one, because an app written against HomeKit’s motion sensor should not have its feature vanish on Android. Just do not treat the two as independent signals.

Whether a space is occupied.

HomeKit: OccupancyDetected. Matter: Occupancy Sensing 0x0406, bit 0 of Occupancy. See MOTION_DETECTED for why the two coincide on Matter.

Whether a contact sensor is closed. True means the door or window is shut.

The polarity is worth stating twice because the platforms differ: HomeKit’s ContactState is an inverted integer where 0 means closed, and Matter’s Boolean State 0x0045 StateValue is a boolean where true means closed. This API follows Matter and the iOS port inverts.

Whether water is being detected.

HomeKit: LeakDetected. Matter: the Water Leak Detector device type over Boolean State 0x0045, where true means a leak.

Note that Boolean State means the opposite thing here than it does for CONTACT_DETECTED, because its polarity is fixed by the device type rather than by the cluster. That is why the ports’ mapping tables key on device type, cluster and attribute together, never on the cluster alone.

Whether smoke is being detected, as an AlarmState.

HomeKit: SmokeDetected, two-state, so it can only ever report AlarmState.NORMAL or AlarmState.CRITICAL.

Matter: Smoke CO Alarm 0x005C, SmokeState, three-state, so AlarmState.WARNING is reachable there.

Read AlarmState’s note before building anything on this. It is not a fire-alarm channel.

Whether carbon monoxide is being detected, as an AlarmState.

HomeKit: CarbonMonoxideDetected, two-state. Matter: Smoke CO Alarm 0x005C, COState, three-state. Same asymmetry as SMOKE_DETECTED, and the same warning.

Measured carbon monoxide, in parts per million.

HomeKit: CarbonMonoxideLevel, already ppm.

Matter: Carbon Monoxide Concentration Measurement 0x040C, whose MeasurementUnit is chosen by the accessory and may be a mass concentration. Where the accessory reports mass per volume the port reports no value, because converting needs the gas’s molar mass and the ambient temperature and pressure, and inventing those would produce a number that looks like a measurement.

Measured carbon dioxide, in parts per million.

HomeKit: CarbonDioxideLevel. Matter: Carbon Dioxide Concentration Measurement 0x040D. Same unit caveat as CO_LEVEL.

A summarized air-quality rating, as an AirQualityLevel.

HomeKit: AirQuality, six levels. Matter: Air Quality 0x005B, seven. The enum documents how they are reconciled and which constant HomeKit can never produce. Do not hard-code thresholds against it and expect them to describe the same air on both platforms.

Fine particulate matter, in micrograms per cubic metre.

HomeKit: PM2_5Density. Matter: PM2.5 Concentration 0x042A, where the accessory’s own MeasurementUnit has to match; see CO_LEVEL.

Coarse particulate matter, in micrograms per cubic metre.

HomeKit: PM10Density. Matter: PM10 Concentration 0x042D.

Total volatile organic compounds.

HomeKit reports these in micrograms per cubic metre; Matter’s Total VOC Concentration 0x042E is commonly in parts per billion. The unit therefore varies by accessory, which is exactly why TraitValue.getDouble(TraitUnit) makes you name the one you expect and refuses to convert between the two dimensions. Read TraitValue.getUnit() before you render this one.

How much battery an accessory has left, as a percentage.

HomeKit: BatteryLevel, already 0 to 100. Matter: Power Source 0x002F, BatPercentRemaining, which is in half percent and runs 0 to 200. The port halves it; application code sees percent.

Whether the battery is charging, as a ChargingState.

HomeKit: ChargingState. Matter: Power Source 0x002F, BatChargeState. The enum documents which constants each backend can never produce – notably that HomeKit cannot tell a full battery on a charger from one that is running down.

Whether the battery is low enough to want attention.

HomeKit: StatusLowBattery, two-state. Matter: Power Source 0x002F, BatChargeLevel, whose warning and critical levels both arrive here as true – a small loss, and the only one on this trait.

How fast a fan is running, as a percentage.

HomeKit: RotationSpeed, one characteristic for both reading and writing.

Matter splits it: Fan Control 0x0202 has PercentSetting for what was asked and PercentCurrent for what the motor is actually doing. Writes go to the former and reads come from the latter, so a read immediately after a write can still show the old speed while the fan ramps. That is the accessory being honest, not a stale cache.

How a fan is running, as a FanMode.

Matter: Fan Control 0x0202, FanMode, seven values. HomeKit has no real equivalent, and the enum documents the translation – including that low, medium and high are written as speeds on iOS and never read back. If your UI shows a speed, read FAN_SPEED instead; it behaves the same everywhere.

Speaker volume, as a percentage.

HomeKit: Volume on a speaker service. Matter: the speaker device type’s Level Control, 0 to 254, with the same quantization as BRIGHTNESS.

Expect this to be unsupported on almost every real accessory. HomeKit’s speaker service is in practice only exposed by cameras and doorbells – AirPlay speakers and HomePods are not HomeKit accessories and do not appear in the graph at all – and Matter speakers barely exist in the field. This is not a media-playback API.

Whether a speaker is muted.

HomeKit: Mute, a plain boolean. Matter: the speaker device type uses On/Off, where off means muted – inverted. The port flips it.

Same availability caveat as VOLUME.

Whether this trait can only ever be read.

Whether a reading of this trait may arrive in the given unit.

The trait’s own unit always may. So may one of the alternates, which exist for the traits whose javadoc says the unit varies by accessory – VOC arrives in micrograms per cubic metre from HomeKit and in parts per billion from Matter, and refusing the second would refuse a reading this API promises to deliver.

Whether a value belongs to this trait’s domain enum.

Checked by constant name where the value has one, which is every value an application builds, and by ordinal range otherwise – the codec decodes a wire ordinal with no constant in hand.

A value out of the wrong enum is not a curiosity: every enum crosses the wire as an ordinal, and AlarmState.WARNING and LockState.UNSECURED are both 1. Asking a door lock for an alarm state, unguarded, unlocks the door.

Whether a value may be WRITTEN to this trait.

Narrower than acceptsEnumValue(TraitValue) for a target enum that carries states an accessory reports and cannot be asked for: a door that is OPENING, a thermostat mode HomeKit cannot express. Each enum says the same thing with its own isWritable(); this is the form the write path can check when it has an ordinal rather than a constant.

The bottom of this trait’s documented range, in getUnit().

Documentation, not validation. What a given accessory will actually accept is on its TraitConstraint, which is where a write is checked; a dimmer whose real floor is 10 percent says so there.

Resolves a trait by its getId(), total: an unknown or null id answers null rather than throwing.

Total because ids arrive from outside – a persisted favourite, a build hint, a port built against a newer version of this table. An unrecognized one is a value to skip, not a reason to fail a decode that still has good rows in it.