tessl/pypi-home-assistant-chip-clusters
Python APIs and tools for Matter (Project CHIP) protocol implementation, specifically the chip clusters functionality used by Home Assistant for Matter device control and communication
—
Pending
clusters.mddocs/
Matter Clusters
Complete implementation of Matter clusters (170+ cluster types) providing standardized device interaction patterns for smart home devices including lighting, sensors, HVAC, security, and more.
Capabilities
Lighting Control Clusters
Control various aspects of lighting devices including on/off state, dimming levels, and color.
class OnOff:
"""On/Off cluster for basic device power control."""
class Attributes:
OnOff: int # Current on/off state (0=off, 1=on)
GlobalSceneControl: bool # Global scene control flag
OnTime: int # On time in 1/10ths of a second
OffWaitTime: int # Off wait time in 1/10ths of a second
StartUpOnOff: int # Startup behavior
class Commands:
class Off:
"""Turn device off."""
def __init__(self): ...
class On:
"""Turn device on."""
def __init__(self): ...
class Toggle:
"""Toggle device state."""
def __init__(self): ...
class OffWithEffect:
"""Turn off with effect."""
def __init__(self, effectId: int, effectVariant: int): ...
class OnWithRecallGlobalScene:
"""Turn on and recall global scene."""
def __init__(self): ...
class OnWithTimedOff:
"""Turn on with timed off."""
def __init__(self, onOffControl: int, onTime: int, offWaitTime: int): ...
class LevelControl:
"""Level control cluster for dimming and level adjustment."""
class Attributes:
CurrentLevel: int # Current level (0-254, null if unknown)
RemainingTime: int # Remaining transition time
MinLevel: int # Minimum level value
MaxLevel: int # Maximum level value
CurrentFrequency: int # Current frequency
MinFrequency: int # Minimum frequency
MaxFrequency: int # Maximum frequency
OnOffTransitionTime: int # Transition time for on/off
OnLevel: int # Level for on command
OnTransitionTime: int # Transition time for on
OffTransitionTime: int # Transition time for off
DefaultMoveRate: int # Default move rate
Options: int # Level control options
StartUpCurrentLevel: int # Startup current level
class Commands:
class MoveToLevel:
"""Move to specific level."""
def __init__(self, level: int, transitionTime: int, optionsMask: int = 0, optionsOverride: int = 0): ...
class Move:
"""Move up or down."""
def __init__(self, moveMode: int, rate: int, optionsMask: int = 0, optionsOverride: int = 0): ...
class Step:
"""Step up or down."""
def __init__(self, stepMode: int, stepSize: int, transitionTime: int, optionsMask: int = 0, optionsOverride: int = 0): ...
class Stop:
"""Stop level change."""
def __init__(self, optionsMask: int = 0, optionsOverride: int = 0): ...
class MoveToLevelWithOnOff:
"""Move to level with on/off."""
def __init__(self, level: int, transitionTime: int, optionsMask: int = 0, optionsOverride: int = 0): ...
class ColorControl:
"""Color control cluster for color-capable lighting devices."""
class Attributes:
CurrentHue: int # Current hue value (0-254)
CurrentSaturation: int # Current saturation (0-254)
RemainingTime: int # Remaining transition time
CurrentX: int # Current CIE x coordinate
CurrentY: int # Current CIE y coordinate
DriftCompensation: int # Drift compensation
CompensationText: str # Compensation text
ColorTemperatureMireds: int # Color temperature in mireds
ColorMode: int # Current color mode
Options: int # Color control options
NumberOfPrimaries: int # Number of color primaries
Primary1X: int # Primary 1 x coordinate
Primary1Y: int # Primary 1 y coordinate
Primary1Intensity: int # Primary 1 intensity
ColorPointRed: tuple # Red color point (x, y)
ColorPointGreen: tuple # Green color point (x, y)
ColorPointBlue: tuple # Blue color point (x, y)
WhitePointX: int # White point x coordinate
WhitePointY: int # White point y coordinate
ColorTempPhysicalMinMireds: int # Physical minimum color temperature
ColorTempPhysicalMaxMireds: int # Physical maximum color temperature
CoupleColorTempToLevelMinMireds: int # Coupling minimum temperature
StartUpColorTemperatureMireds: int # Startup color temperature
class Commands:
class MoveToHue:
"""Move to specific hue."""
def __init__(self, hue: int, direction: int, transitionTime: int, optionsMask: int = 0, optionsOverride: int = 0): ...
class MoveHue:
"""Move hue continuously."""
def __init__(self, moveMode: int, rate: int, optionsMask: int = 0, optionsOverride: int = 0): ...
class StepHue:
"""Step hue by amount."""
def __init__(self, stepMode: int, stepSize: int, transitionTime: int, optionsMask: int = 0, optionsOverride: int = 0): ...
class MoveToSaturation:
"""Move to specific saturation."""
def __init__(self, saturation: int, transitionTime: int, optionsMask: int = 0, optionsOverride: int = 0): ...
class MoveSaturation:
"""Move saturation continuously."""
def __init__(self, moveMode: int, rate: int, optionsMask: int = 0, optionsOverride: int = 0): ...
class StepSaturation:
"""Step saturation by amount."""
def __init__(self, stepMode: int, stepSize: int, transitionTime: int, optionsMask: int = 0, optionsOverride: int = 0): ...
class MoveToHueAndSaturation:
"""Move to specific hue and saturation."""
def __init__(self, hue: int, saturation: int, transitionTime: int, optionsMask: int = 0, optionsOverride: int = 0): ...
class MoveToColor:
"""Move to specific color (x, y)."""
def __init__(self, colorX: int, colorY: int, transitionTime: int, optionsMask: int = 0, optionsOverride: int = 0): ...
class MoveToColorTemperature:
"""Move to specific color temperature."""
def __init__(self, colorTemperatureMireds: int, transitionTime: int, optionsMask: int = 0, optionsOverride: int = 0): ...Sensor Clusters
Read environmental and occupancy sensor data from Matter devices.
class TemperatureMeasurement:
"""Temperature measurement cluster."""
class Attributes:
MeasuredValue: int # Measured temperature in 1/100ths of degrees Celsius (null if unknown)
MinMeasuredValue: int # Minimum measurable temperature
MaxMeasuredValue: int # Maximum measurable temperature
Tolerance: int # Measurement tolerance
class RelativeHumidityMeasurement:
"""Relative humidity measurement cluster."""
class Attributes:
MeasuredValue: int # Measured humidity in 1/100ths of percent (null if unknown)
MinMeasuredValue: int # Minimum measurable humidity
MaxMeasuredValue: int # Maximum measurable humidity
Tolerance: int # Measurement tolerance
class IlluminanceMeasurement:
"""Illuminance measurement cluster."""
class Attributes:
MeasuredValue: int # Measured illuminance in lux (null if unknown)
MinMeasuredValue: int # Minimum measurable illuminance
MaxMeasuredValue: int # Maximum measurable illuminance
Tolerance: int # Measurement tolerance
LightSensorType: int # Type of light sensor
class OccupancySensing:
"""Occupancy sensing cluster."""
class Attributes:
Occupancy: int # Occupancy bitmap (bit 0: occupied)
OccupancySensorType: int # Type of occupancy sensor
OccupancySensorTypeBitmap: int # Occupancy sensor type bitmap
PIROccupiedToUnoccupiedDelay: int # PIR occupied to unoccupied delay
PIRUnoccupiedToOccupiedDelay: int # PIR unoccupied to occupied delay
PIRUnoccupiedToOccupiedThreshold: int # PIR unoccupied to occupied threshold
UltrasonicOccupiedToUnoccupiedDelay: int # Ultrasonic delays
UltrasonicUnoccupiedToOccupiedDelay: int
UltrasonicUnoccupiedToOccupiedThreshold: int
PhysicalContactOccupiedToUnoccupiedDelay: int # Physical contact delays
PhysicalContactUnoccupiedToOccupiedDelay: int
PhysicalContactUnoccupiedToOccupiedThreshold: int
class PressureMeasurement:
"""Pressure measurement cluster."""
class Attributes:
MeasuredValue: int # Measured pressure in kPa (null if unknown)
MinMeasuredValue: int # Minimum measurable pressure
MaxMeasuredValue: int # Maximum measurable pressure
Tolerance: int # Measurement tolerance
ScaledValue: int # Scaled measured value
MinScaledValue: int # Minimum scaled value
MaxScaledValue: int # Maximum scaled value
ScaledTolerance: int # Scaled tolerance
Scale: int # Scale factorHVAC Control Clusters
Control heating, ventilation, and air conditioning systems.
class Thermostat:
"""Thermostat cluster for temperature control."""
class Attributes:
LocalTemperature: int # Local temperature in 1/100ths degrees Celsius
OutdoorTemperature: int # Outdoor temperature
Occupancy: int # Occupancy status
AbsMinHeatSetpointLimit: int # Absolute minimum heat setpoint
AbsMaxHeatSetpointLimit: int # Absolute maximum heat setpoint
AbsMinCoolSetpointLimit: int # Absolute minimum cool setpoint
AbsMaxCoolSetpointLimit: int # Absolute maximum cool setpoint
PICoolingDemand: int # PI cooling demand
PIHeatingDemand: int # PI heating demand
HVACSystemTypeConfiguration: int # HVAC system type
LocalTemperatureCalibration: int # Local temperature calibration
OccupiedCoolingSetpoint: int # Occupied cooling setpoint
OccupiedHeatingSetpoint: int # Occupied heating setpoint
UnoccupiedCoolingSetpoint: int # Unoccupied cooling setpoint
UnoccupiedHeatingSetpoint: int # Unoccupied heating setpoint
MinHeatSetpointLimit: int # Minimum heat setpoint limit
MaxHeatSetpointLimit: int # Maximum heat setpoint limit
MinCoolSetpointLimit: int # Minimum cool setpoint limit
MaxCoolSetpointLimit: int # Maximum cool setpoint limit
MinSetpointDeadBand: int # Minimum setpoint dead band
RemoteSensing: int # Remote sensing bitmap
ControlSequenceOfOperation: int # Control sequence
SystemMode: int # System mode (off, auto, cool, heat, etc.)
ThermostatRunningState: int # Running state bitmap
SetpointChangeSource: int # Setpoint change source
SetpointChangeAmount: int # Setpoint change amount
SetpointChangeSourceTimestamp: int # Setpoint change timestamp
OccupiedSetback: int # Occupied setback
OccupiedSetbackMin: int # Occupied setback minimum
OccupiedSetbackMax: int # Occupied setback maximum
UnoccupiedSetback: int # Unoccupied setback
UnoccupiedSetbackMin: int # Unoccupied setback minimum
UnoccupiedSetbackMax: int # Unoccupied setback maximum
EmergencyHeatDelta: int # Emergency heat delta
ACType: int # AC type
ACCapacity: int # AC capacity
ACRefrigerantType: int # AC refrigerant type
ACCompressorType: int # AC compressor type
ACErrorCode: int # AC error code
ACLouverPosition: int # AC louver position
ACCoilTemperature: int # AC coil temperature
ACCapacityformat: int # AC capacity format
class Commands:
class SetpointRaiseLower:
"""Raise or lower setpoint."""
def __init__(self, mode: int, amount: int): ...
class SetWeeklySchedule:
"""Set weekly schedule."""
def __init__(self, numberOfTransitionsForSequence: int, dayOfWeekForSequence: int, modeForSequence: int, transitions: list): ...
class GetWeeklySchedule:
"""Get weekly schedule."""
def __init__(self, daysToReturn: int, modeToReturn: int): ...
class ClearWeeklySchedule:
"""Clear weekly schedule."""
def __init__(self): ...
class Fan:
"""Fan control cluster."""
class Attributes:
FanMode: int # Fan mode (off, low, medium, high, on, auto, smart)
FanModeSequence: int # Fan mode sequence
PercentSetting: int # Percent setting (0-100)
PercentCurrent: int # Current percent
SpeedMax: int # Maximum speed
SpeedSetting: int # Speed setting
SpeedCurrent: int # Current speed
RockSupport: int # Rock support bitmap
RockSetting: int # Rock setting
WindSupport: int # Wind support bitmap
WindSetting: int # Wind setting
class Commands:
class Step:
"""Step fan speed."""
def __init__(self, direction: int, wrap: bool, lowestOff: bool): ...Security and Access Control
Manage door locks, access control, and security systems.
class DoorLock:
"""Door lock cluster for access control."""
class Attributes:
LockState: int # Current lock state (locked, unlocked, not fully locked, unknown)
LockType: int # Type of lock
ActuatorEnabled: bool # Whether actuator is enabled
DoorState: int # Door state (open, closed, error, forced open, unknown, ajar)
DoorOpenEvents: int # Number of door open events
DoorClosedEvents: int # Number of door closed events
OpenPeriod: int # Door open period
NumberOfLogRecordsSupported: int # Number of log records supported
NumberOfTotalUsersSupported: int # Total users supported
NumberOfPINUsersSupported: int # PIN users supported
NumberOfRFIDUsersSupported: int # RFID users supported
NumberOfWeekDaySchedulesSupportedPerUser: int # Week day schedules per user
NumberOfYearDaySchedulesSupportedPerUser: int # Year day schedules per user
NumberOfHolidaySchedulesSupported: int # Holiday schedules supported
MaxPINCodeLength: int # Maximum PIN code length
MinPINCodeLength: int # Minimum PIN code length
MaxRFIDCodeLength: int # Maximum RFID code length
MinRFIDCodeLength: int # Minimum RFID code length
CredentialRulesSupport: int # Credential rules support bitmap
NumberOfCredentialsSupportedPerUser: int # Credentials per user
Language: str # Language setting
LEDSettings: int # LED settings
AutoRelockTime: int # Auto relock time in seconds
SoundVolume: int # Sound volume
OperatingMode: int # Operating mode
SupportedOperatingModes: int # Supported operating modes bitmap
DefaultConfigurationRegister: int # Default configuration
EnableLocalProgramming: bool # Enable local programming
EnableOneTouchLocking: bool # Enable one touch locking
EnableInsideStatusLED: bool # Enable inside status LED
EnablePrivacyModeButton: bool # Enable privacy mode button
LocalProgrammingFeatures: int # Local programming features bitmap
WrongCodeEntryLimit: int # Wrong code entry limit
UserCodeTemporaryDisableTime: int # User code temporary disable time
SendPINOverTheAir: bool # Send PIN over the air
RequirePINforRemoteOperation: bool # Require PIN for remote operation
ExpiringUserTimeout: int # Expiring user timeout
class Commands:
class LockDoor:
"""Lock the door."""
def __init__(self, pinCode: bytes = None): ...
class UnlockDoor:
"""Unlock the door."""
def __init__(self, pinCode: bytes = None): ...
class UnlockWithTimeout:
"""Unlock with timeout."""
def __init__(self, timeout: int, pinCode: bytes = None): ...
class GetLogRecord:
"""Get log record."""
def __init__(self, logIndex: int): ...
class SetPINCode:
"""Set PIN code."""
def __init__(self, userId: int, userStatus: int, userType: int, pinCode: bytes): ...
class GetPINCode:
"""Get PIN code."""
def __init__(self, userId: int): ...
class ClearPINCode:
"""Clear PIN code."""
def __init__(self, userId: int): ...
class ClearAllPINCodes:
"""Clear all PIN codes."""
def __init__(self): ...
class SetUserStatus:
"""Set user status."""
def __init__(self, userId: int, userStatus: int): ...
class GetUserStatus:
"""Get user status."""
def __init__(self, userId: int): ...
class SetWeekDaySchedule:
"""Set week day schedule."""
def __init__(self, scheduleId: int, userId: int, daysMask: int, startHour: int, startMinute: int, endHour: int, endMinute: int): ...
class GetWeekDaySchedule:
"""Get week day schedule."""
def __init__(self, scheduleId: int, userId: int): ...
class ClearWeekDaySchedule:
"""Clear week day schedule."""
def __init__(self, scheduleId: int, userId: int): ...
class SetYearDaySchedule:
"""Set year day schedule."""
def __init__(self, scheduleId: int, userId: int, localStartTime: int, localEndTime: int): ...
class GetYearDaySchedule:
"""Get year day schedule."""
def __init__(self, scheduleId: int, userId: int): ...
class ClearYearDaySchedule:
"""Clear year day schedule."""
def __init__(self, scheduleId: int, userId: int): ...
class SetHolidaySchedule:
"""Set holiday schedule."""
def __init__(self, scheduleId: int, localStartTime: int, localEndTime: int, operatingMode: int): ...
class GetHolidaySchedule:
"""Get holiday schedule."""
def __init__(self, scheduleId: int): ...
class ClearHolidaySchedule:
"""Clear holiday schedule."""
def __init__(self, scheduleId: int): ...
class SetUser:
"""Set user."""
def __init__(self, operationType: int, userIndex: int, userName: str, userUniqueId: int, userStatus: int, userType: int, credentialRule: int): ...
class GetUser:
"""Get user."""
def __init__(self, userIndex: int): ...
class ClearUser:
"""Clear user."""
def __init__(self, userIndex: int): ...
class SetCredential:
"""Set credential."""
def __init__(self, operationType: int, credential: dict, credentialData: bytes, userIndex: int, userStatus: int, userType: int): ...
class GetCredentialStatus:
"""Get credential status."""
def __init__(self, credential: dict): ...
class ClearCredential:
"""Clear credential."""
def __init__(self, credential: dict): ...Window Covering Control
Control motorized window coverings, blinds, and shades.
class WindowCovering:
"""Window covering control cluster."""
class Attributes:
Type: int # Window covering type
PhysicalClosedLimitLift: int # Physical closed limit lift
PhysicalClosedLimitTilt: int # Physical closed limit tilt
CurrentPositionLift: int # Current lift position (0-10000, null if unknown)
CurrentPositionTilt: int # Current tilt position (0-10000, null if unknown)
NumberOfActuationsLift: int # Number of lift actuations
NumberOfActuationsTilt: int # Number of tilt actuations
ConfigStatus: int # Configuration status bitmap
CurrentPositionLiftPercentage: int # Current lift position percentage (0-100, null if unknown)
CurrentPositionTiltPercentage: int # Current tilt position percentage (0-100, null if unknown)
OperationalStatus: int # Operational status bitmap
TargetPositionLiftPercent100ths: int # Target lift position in 1/100ths percent
TargetPositionTiltPercent100ths: int # Target tilt position in 1/100ths percent
EndProductType: int # End product type
Mode: int # Window covering mode bitmap
SafetyStatus: int # Safety status bitmap
class Commands:
class UpOrOpen:
"""Move covering up or open."""
def __init__(self): ...
class DownOrClose:
"""Move covering down or close."""
def __init__(self): ...
class StopMotion:
"""Stop covering motion."""
def __init__(self): ...
class GoToLiftValue:
"""Go to specific lift value."""
def __init__(self, liftValue: int): ...
class GoToLiftPercentage:
"""Go to specific lift percentage."""
def __init__(self, liftPercent100thsValue: int): ...
class GoToTiltValue:
"""Go to specific tilt value."""
def __init__(self, tiltValue: int): ...
class GoToTiltPercentage:
"""Go to specific tilt percentage."""
def __init__(self, tiltPercent100thsValue: int): ...Usage Examples
Basic Lighting Control
import chip.clusters as Clusters
from chip.ChipDeviceCtrl import ChipDeviceController
controller = ChipDeviceController(controllerNodeId=12345)
# Turn on a light
controller.SendCommand(
nodeid=1,
endpoint=1,
Clusters.OnOff.Commands.On()
)
# Dim to 50%
controller.SendCommand(
nodeid=1,
endpoint=1,
Clusters.LevelControl.Commands.MoveToLevel(
level=127, # 50% of 254
transitionTime=10 # 1 second transition
)
)
# Change color to red (hue=0, saturation=254)
controller.SendCommand(
nodeid=1,
endpoint=1,
Clusters.ColorControl.Commands.MoveToHueAndSaturation(
hue=0,
saturation=254,
transitionTime=20
)
)Sensor Reading
# Read temperature sensor
temp_result = controller.ReadAttribute(
nodeid=2,
attributes=[(1, Clusters.TemperatureMeasurement.Attributes.MeasuredValue)]
)
if temp_result:
temp_raw = temp_result[(1, Clusters.TemperatureMeasurement.id, Clusters.TemperatureMeasurement.Attributes.MeasuredValue.attribute_id)]
if temp_raw is not None:
temperature_celsius = temp_raw / 100.0
print(f"Temperature: {temperature_celsius}°C")
# Check occupancy sensor
occupancy_result = controller.ReadAttribute(
nodeid=3,
attributes=[(1, Clusters.OccupancySensing.Attributes.Occupancy)]
)
if occupancy_result:
occupancy = occupancy_result[(1, Clusters.OccupancySensing.id, Clusters.OccupancySensing.Attributes.Occupancy.attribute_id)]
is_occupied = bool(occupancy & 0x01)
print(f"Occupancy: {'Occupied' if is_occupied else 'Unoccupied'}")Thermostat Control
# Set thermostat to 72°F (2222 = 22.22°C)
controller.WriteAttribute(
nodeid=4,
attributes=[(1, Clusters.Thermostat.Attributes.OccupiedHeatingSetpoint, 2222)]
)
# Change to cooling mode
controller.WriteAttribute(
nodeid=4,
attributes=[(1, Clusters.Thermostat.Attributes.SystemMode, 3)] # 3 = Cool
)
# Raise setpoint by 1°C
controller.SendCommand(
nodeid=4,
endpoint=1,
Clusters.Thermostat.Commands.SetpointRaiseLower(
mode=0, # 0 = heat, 1 = cool, 2 = both
amount=100 # 1°C in 1/100ths
)
)Door Lock Control
# Lock door with PIN
controller.SendCommand(
nodeid=5,
endpoint=1,
Clusters.DoorLock.Commands.LockDoor(
pinCode=b"1234"
)
)
# Unlock door temporarily for 30 seconds
controller.SendCommand(
nodeid=5,
endpoint=1,
Clusters.DoorLock.Commands.UnlockWithTimeout(
timeout=30,
pinCode=b"1234"
)
)
# Check lock state
lock_state = controller.ReadAttribute(
nodeid=5,
attributes=[(1, Clusters.DoorLock.Attributes.LockState)]
)Install with Tessl CLI
npx tessl i tessl/pypi-home-assistant-chip-clusters