Zone

class aaa_modules.layout_model.zone.Level

The vertical levels.

BASEMENT = 0

The basement

FIRST_FLOOR = 1

The first floor

SECOND_FLOOR = 2

The second floor

THIRD_FLOOR = 3

The third floor

UNDEFINED = -1

Undefined

class aaa_modules.layout_model.zone.Zone(name, devices=[], level=-1, neighbors=[])

Represent a zone such as a room, foyer, porch, or lobby. Each zone holds a number of devices/sensors such as switches, motion sensors, or temperature sensors.

A zone might have zero, one or multiple adjacent zones. The adjacent zones can be further classified into closed space (i.e. a wall exists between the two zones, open space, open space slave (the neighbor is a less important zone), and open space master. This layout-like structure is useful for certain scenario such as light control.

Each zone instance is IMMUTABLE. The various add/remove methods return a new Zone object. Note however that the OpenHab item underlying each device/sensor is not (the state changes). See addDevice(), removeDevice(), addNeighbor()

The zone itself doesn’t know how to operate a device/sensor. The sensors themselves (all sensors derive from Device class) exposes the possible operations. Generally, the zone needs not know about the exact types of sensors it contains. However, controlling the light is a very common case for home automation; thus it does references to several virtual/physical sensors to determine the astro time, the illuminance, and the motion sensor. See getDevices(), getDevicesByType().

There are two sets of operation on each zone:

1. Active operations such as turn on a light/fan in a zone. These are represented by common functions such as #turnOnLights(), #turnOffLights(); and
2. Passive operations triggered by events such onTimerExpired(), onSwitchTurnedOn(), and so on.

The passive triggering is needed because the interaction with the devices or sensors might happen outside the interface exposed by this class. It could be a manually action on the switch by the user, or a direct send command through the OpenHab event bus. All the onXxx methods accept two parameters: the core.jsr223.scope.events object and the string itemName. The zone will perform appropriate actions for each of these events. For example, a motion event will turn on the light if it is dark or if it is evening time; a timer expiry event will turn off the associated light if it is currently on.

@Immutable (the Zone object only)

__init__(name, devices=[], level=-1, neighbors=[])

Creates a new zone.

Parameters:

• name (str) – the zone name
• devices (list(Device)) – the list of Device objects
• level (zone.Level) – the zone’s physical level
• neighbors (list(Neigbor)) – the list of optional neighbor zones.

addDevice(device)

Creates a new zone that is an exact copy of this one, but has the additional device.

Returns:A NEW object. Return type:Zone

addNeighbor(neighbor)

Creates a new zone that is an exact copy of this one, but has the additional neighbor.

Returns:A NEW object. Return type:Zone

containsOpenHabItem(itemName, sensorType=None)

Returns True if this zone contains the given itemName; returns False otherwise.

Parameters:

• itemName (str) –
• sensorType (Device) – an optional sub-class of Device. If specified, will search for itemName for those device types only. Otherwise, search for all devices/sensors.

Return type:

bool

getDevices()

Returns a copy of the list of devices.

Return type:list(Device)

getDevicesByType(cls)

Returns a list of devices matching the given type.

Parameters:cls (Device) – the device type

getId()

Return type:str

getIlluminanceLevel()

Retrieves the maximum illuminance level from one or more IlluminanceSensor. If no sensor is available, return -1.

Return type:int

getLevel()

Return type:zone.Level

getName()

Return type:str

getNeighbors()

Returns:a copy of the list of neighboring zones. Return type:list(Neighbor)

isLightOn()

Returns True if at least one light is on; returns False otherwise.

Return type:bool

isLightOnTime()

Returns True if it is light-on time; returns false if it is no. Returns None if there is no AstroSensor to determine the time.

Return type:bool or None

isOccupied(minutesFromLastMotionEvent=5)

Returns True if the zone has at least one switch turned on, or if a motion event was triggered within the provided # of minutes.

Return type:bool

onMotionSensorTurnedOn(events, itemName, getZoneByIdFn)

If the motion sensor belongs to this zone, turns on the associated switch, and returns True. Otherwise return False.

Parameters:getZoneByIdFn (lambda) – a function that returns a Zone object given a zone id string Return type:boolean

onSwitchTurnedOff(events, itemName)

If itemName belongs to this zone, dispatches the event to the associated Switch object, and returns True. Otherwise return False.

See Switch.onSwitchTurnedOff()

Return type:boolean

onSwitchTurnedOn(events, itemName, getZoneByIdFn)

If itemName belongs to this zone, dispatches the event to the associated Switch object, and returns True. Otherwise return False.

See Switch.onSwitchTurnedOn()

Parameters:getZoneByIdFn (lambda) – a function that returns a Zone object given a zone id string Return type:boolean

onTimerExpired(events, itemName)

Determines if the timer itemName is associated with a switch in this zone; if yes, turns off the switch and returns True. Otherwise returns False.

removeDevice(device)

Creates a new zone that is an exact copy of this one less the given device

Returns:A NEW object. Return type:Zone

shareSensorWith(zone, sensorType)

Returns True if this zone shares at least one sensor of the given sensorType with the provider zone. Two sensors are considered the same if they link to the same channel.

See Device.getChannel()

Return type:bool

turnOffLights(events)

Turn off all the lights in the zone.

Parameters:events (scope.events) –