Sets¶

Sets are arbitrary, volatile collections of devices. They are a high-level construct that should hide the complexity of the dS system from the user of the dSS API. Operations on a set are the same as operations on zone or a single device. You can turn on all devices contained in a set like you can turn on all devices in a zone. The dSS tries to optimize your sets to have minimal traffic on the dS bus.
To construct/describe a set there is a special set syntax which is described in the next section.

At this time its not possible to store sets in the dS system but a issue has been created (#279) to implement that. But even with this feature in place you will be using the set-notation to describe your set. The difference will be that this set may be directly mapped to a custom group in the dS system and thus be called really fast.

Set syntax¶

When using sets you're restricting a set of devices to a subset of the original set. Multiple restrictions may be joined by a dot. Consider the following setup:

We have two zones (named "bath" and "kitchen") and six devices. Three of those devices are in the same group ("yellow"). If you want all yellow devices in the kitchen the expression in the set notation would be:

.yellow.kitchen

The '.' at the beginning selects all devices known to the dSS. Appending a name to the set-description restricts the set to all devices contained in a container (a group or a zone) named like that or a device with that name. So adding yellow to the description restricts all devices (the '.') to "all devices within the group yellow". By adding .kitchen the set gets restricted to "all devices within the group yellow which are located in the zone named kitchen".
The result of this operation would be a set containing the device dev6.
Of course the same applies if the names were restricted the other way around like that:

.kitchen.yellow

Since zones and groups could be named the same it's possible to write restrictions more expressively:

.group('yellow').zone('kitchen')

This tells the dSS to explicitly look for a group named yellow and a zone name kitchen. If they're not found, the operators return an empty set.

Operators¶

• dot (.)
  If at the start of a set notation it selects all devices known to the dSS. Otherwise it's just a separator for different restrictions.
• ._name_
  Restricts to a group/zone/device with that name or devices contained within it.

Special functions¶

• .dsid(id)
  Restrict to a device with the given id.
• .fid(id)
  Restricts to devices having the given function id.
• .group('name' | id)
  Restricts to devices contained within the group named name or having the id id,
• .zone('name' | id)
  Restricts to devices contained within the zone named name or having the id id,
• .empty()
  Empties the set, see addDevices
• .addDevices('name' | id, [_'name'_ | id, ...])
  Special command that adds some devices to a set.
• .tag('name')
  Restricts to devices being tagged by name

Set operations¶

• .add(set)
  Combines two sets (union)
• .remove(set)
  Removes a set from the other (difference)