Homematic next (#11156)

* Cleanup logic & New gen of HomeMatic

* fix lint

* cleanup

* fix coverage

* cleanup

* name consistenc

* fix lint

* Rename ip

* cleanup wrong property

* fix bug

* handle callback better

* fix lint

* Running now

.coveragerc

@@ -88,7 +88,7 @@ omit =
     homeassistant/components/hive.py
     homeassistant/components/*/hive.py
 
-    homeassistant/components/homematic.py
+    homeassistant/components/homematic/__init__.py
     homeassistant/components/*/homematic.py
 
     homeassistant/components/insteon_local.py

homeassistant/components/homematic/__init__.py

@@ -12,14 +12,13 @@ from functools import partial
 
 import voluptuous as vol
 
-import homeassistant.helpers.config_validation as cv
+from homeassistant.config import load_yaml_config_file
 from homeassistant.const import (
-    EVENT_HOMEASSISTANT_STOP, STATE_UNKNOWN, CONF_USERNAME, CONF_PASSWORD,
+    EVENT_HOMEASSISTANT_STOP, CONF_USERNAME, CONF_PASSWORD, CONF_PLATFORM,
-    CONF_PLATFORM, CONF_HOSTS, CONF_NAME, ATTR_ENTITY_ID)
+    CONF_HOSTS, CONF_HOST, ATTR_ENTITY_ID, STATE_UNKNOWN)
 from homeassistant.helpers import discovery
 from homeassistant.helpers.entity import Entity
-from homeassistant.helpers.event import track_time_interval
+import homeassistant.helpers.config_validation as cv
-from homeassistant.config import load_yaml_config_file
 
 REQUIREMENTS = ['pyhomematic==0.1.36']
 
@@ -41,7 +40,7 @@ ATTR_CHANNEL = 'channel'
 ATTR_NAME = 'name'
 ATTR_ADDRESS = 'address'
 ATTR_VALUE = 'value'
-ATTR_PROXY = 'proxy'
+ATTR_INTERFACE = 'interface'
 ATTR_ERRORCODE = 'error'
 ATTR_MESSAGE = 'message'
 
@@ -51,8 +50,8 @@ EVENT_ERROR = 'homematic.error'
 
 SERVICE_VIRTUALKEY = 'virtualkey'
 SERVICE_RECONNECT = 'reconnect'
-SERVICE_SET_VAR_VALUE = 'set_var_value'
+SERVICE_SET_VARIABLE_VALUE = 'set_variable_value'
-SERVICE_SET_DEV_VALUE = 'set_dev_value'
+SERVICE_SET_DEVICE_VALUE = 'set_device_value'
 
 HM_DEVICE_TYPES = {
     DISCOVER_SWITCHES: [
@@ -90,12 +89,14 @@ HM_ATTRIBUTE_SUPPORT = {
     'RSSI_DEVICE': ['rssi', {}],
     'VALVE_STATE': ['valve', {}],
     'BATTERY_STATE': ['battery', {}],
-    'CONTROL_MODE': ['mode', {0: 'Auto',
+    'CONTROL_MODE': ['mode', {
+        0: 'Auto',
         1: 'Manual',
         2: 'Away',
         3: 'Boost',
         4: 'Comfort',
-                              5: 'Lowering'}],
+        5: 'Lowering'
+    }],
     'POWER': ['power', {}],
     'CURRENT': ['current', {}],
     'VOLTAGE': ['voltage', {}],
@@ -124,12 +125,12 @@ CONF_RESOLVENAMES_OPTIONS = [
 ]
 
 DATA_HOMEMATIC = 'homematic'
-DATA_DEVINIT = 'homematic_devinit'
 DATA_STORE = 'homematic_store'
+DATA_CONF = 'homematic_conf'
 
+CONF_INTERFACES = 'interfaces'
 CONF_LOCAL_IP = 'local_ip'
 CONF_LOCAL_PORT = 'local_port'
-CONF_IP = 'ip'
 CONF_PORT = 'port'
 CONF_PATH = 'path'
 CONF_CALLBACK_IP = 'callback_ip'
@@ -146,37 +147,33 @@ DEFAULT_PORT = 2001
 DEFAULT_PATH = ''
 DEFAULT_USERNAME = 'Admin'
 DEFAULT_PASSWORD = ''
-DEFAULT_VARIABLES = False
-DEFAULT_DEVICES = True
-DEFAULT_PRIMARY = False
 
 
 DEVICE_SCHEMA = vol.Schema({
     vol.Required(CONF_PLATFORM): 'homematic',
     vol.Required(ATTR_NAME): cv.string,
     vol.Required(ATTR_ADDRESS): cv.string,
-    vol.Required(ATTR_PROXY): cv.string,
+    vol.Required(ATTR_INTERFACE): cv.string,
     vol.Optional(ATTR_CHANNEL, default=1): vol.Coerce(int),
     vol.Optional(ATTR_PARAM): cv.string,
 })
 
 CONFIG_SCHEMA = vol.Schema({
     DOMAIN: vol.Schema({
-        vol.Required(CONF_HOSTS): {cv.match_all: {
+        vol.Optional(CONF_INTERFACES, default={}): {cv.match_all: {
-            vol.Required(CONF_IP): cv.string,
+            vol.Required(CONF_HOST): cv.string,
             vol.Optional(CONF_PORT, default=DEFAULT_PORT): cv.port,
             vol.Optional(CONF_PATH, default=DEFAULT_PATH): cv.string,
-            vol.Optional(CONF_USERNAME, default=DEFAULT_USERNAME): cv.string,
-            vol.Optional(CONF_PASSWORD, default=DEFAULT_PASSWORD): cv.string,
-            vol.Optional(CONF_VARIABLES, default=DEFAULT_VARIABLES):
-                cv.boolean,
             vol.Optional(CONF_RESOLVENAMES, default=DEFAULT_RESOLVENAMES):
                 vol.In(CONF_RESOLVENAMES_OPTIONS),
-            vol.Optional(CONF_DEVICES, default=DEFAULT_DEVICES): cv.boolean,
-            vol.Optional(CONF_PRIMARY, default=DEFAULT_PRIMARY): cv.boolean,
             vol.Optional(CONF_CALLBACK_IP): cv.string,
             vol.Optional(CONF_CALLBACK_PORT): cv.port,
         }},
+        vol.Optional(CONF_HOSTS, default={}): {cv.match_all: {
+            vol.Required(CONF_HOST): cv.string,
+            vol.Optional(CONF_USERNAME, default=DEFAULT_USERNAME): cv.string,
+            vol.Optional(CONF_PASSWORD, default=DEFAULT_PASSWORD): cv.string,
+        }},
         vol.Optional(CONF_LOCAL_IP, default=DEFAULT_LOCAL_IP): cv.string,
         vol.Optional(CONF_LOCAL_PORT, default=DEFAULT_LOCAL_PORT): cv.port,
     }),
@@ -186,33 +183,33 @@ SCHEMA_SERVICE_VIRTUALKEY = vol.Schema({
     vol.Required(ATTR_ADDRESS): vol.All(cv.string, vol.Upper),
     vol.Required(ATTR_CHANNEL): vol.Coerce(int),
     vol.Required(ATTR_PARAM): cv.string,
-    vol.Optional(ATTR_PROXY): cv.string,
+    vol.Optional(ATTR_INTERFACE): cv.string,
 })
 
-SCHEMA_SERVICE_SET_VAR_VALUE = vol.Schema({
+SCHEMA_SERVICE_SET_VARIABLE_VALUE = vol.Schema({
     vol.Required(ATTR_NAME): cv.string,
     vol.Required(ATTR_VALUE): cv.match_all,
     vol.Optional(ATTR_ENTITY_ID): cv.entity_ids,
 })
 
-SCHEMA_SERVICE_SET_DEV_VALUE = vol.Schema({
+SCHEMA_SERVICE_SET_DEVICE_VALUE = vol.Schema({
     vol.Required(ATTR_ADDRESS): vol.All(cv.string, vol.Upper),
     vol.Required(ATTR_CHANNEL): vol.Coerce(int),
     vol.Required(ATTR_PARAM): vol.All(cv.string, vol.Upper),
     vol.Required(ATTR_VALUE): cv.match_all,
-    vol.Optional(ATTR_PROXY): cv.string,
+    vol.Optional(ATTR_INTERFACE): cv.string,
 })
 
 SCHEMA_SERVICE_RECONNECT = vol.Schema({})
 
 
-def virtualkey(hass, address, channel, param, proxy=None):
+def virtualkey(hass, address, channel, param, interface=None):
     """Send virtual keypress to homematic controlller."""
     data = {
         ATTR_ADDRESS: address,
         ATTR_CHANNEL: channel,
         ATTR_PARAM: param,
-        ATTR_PROXY: proxy,
+        ATTR_INTERFACE: interface,
     }
 
     hass.services.call(DOMAIN, SERVICE_VIRTUALKEY, data)
@@ -225,20 +222,20 @@ def set_var_value(hass, entity_id, value):
         ATTR_VALUE: value,
     }
 
-    hass.services.call(DOMAIN, SERVICE_SET_VAR_VALUE, data)
+    hass.services.call(DOMAIN, SERVICE_SET_VARIABLE_VALUE, data)
 
 
-def set_dev_value(hass, address, channel, param, value, proxy=None):
+def set_dev_value(hass, address, channel, param, value, interface=None):
-    """Call setValue XML-RPC method of supplied proxy."""
+    """Call setValue XML-RPC method of supplied interface."""
     data = {
         ATTR_ADDRESS: address,
         ATTR_CHANNEL: channel,
         ATTR_PARAM: param,
         ATTR_VALUE: value,
-        ATTR_PROXY: proxy,
+        ATTR_INTERFACE: interface,
     }
 
-    hass.services.call(DOMAIN, SERVICE_SET_DEV_VALUE, data)
+    hass.services.call(DOMAIN, SERVICE_SET_DEVICE_VALUE, data)
 
 
 def reconnect(hass):
@@ -250,31 +247,32 @@ def setup(hass, config):
     """Set up the Homematic component."""
     from pyhomematic import HMConnection
 
-    hass.data[DATA_DEVINIT] = {}
+    conf = config[DOMAIN]
+    hass.data[DATA_CONF] = remotes = {}
     hass.data[DATA_STORE] = set()
 
     # Create hosts-dictionary for pyhomematic
-    remotes = {}
+    for rname, rconfig in conf[CONF_INTERFACES].items():
-    hosts = {}
+        remotes[rname] = {
-    for rname, rconfig in config[DOMAIN][CONF_HOSTS].items():
+            'ip': rconfig.get(CONF_HOST),
-        server = rconfig.get(CONF_IP)
+            'port': rconfig.get(CONF_PORT),
-
+            'path': rconfig.get(CONF_PATH),
-        remotes[rname] = {}
+            'resolvenames': rconfig.get(CONF_RESOLVENAMES),
-        remotes[rname][CONF_IP] = server
+            'username': rconfig.get(CONF_USERNAME),
-        remotes[rname][CONF_PORT] = rconfig.get(CONF_PORT)
+            'password': rconfig.get(CONF_PASSWORD),
-        remotes[rname][CONF_PATH] = rconfig.get(CONF_PATH)
+            'callbackip': rconfig.get(CONF_CALLBACK_IP),
-        remotes[rname][CONF_RESOLVENAMES] = rconfig.get(CONF_RESOLVENAMES)
+            'callbackport': rconfig.get(CONF_CALLBACK_PORT),
-        remotes[rname][CONF_USERNAME] = rconfig.get(CONF_USERNAME)
+            'connect': True,
-        remotes[rname][CONF_PASSWORD] = rconfig.get(CONF_PASSWORD)
+        }
-        remotes[rname]['callbackip'] = rconfig.get(CONF_CALLBACK_IP)
+
-        remotes[rname]['callbackport'] = rconfig.get(CONF_CALLBACK_PORT)
+    for sname, sconfig in conf[CONF_HOSTS].items():
-
+        remotes[sname] = {
-        if server not in hosts or rconfig.get(CONF_PRIMARY):
+            'ip': sconfig.get(CONF_HOST),
-            hosts[server] = {
+            'port': DEFAULT_PORT,
-                CONF_VARIABLES: rconfig.get(CONF_VARIABLES),
+            'username': sconfig.get(CONF_USERNAME),
-                CONF_NAME: rname,
+            'password': sconfig.get(CONF_PASSWORD),
+            'connect': False,
         }
-        hass.data[DATA_DEVINIT][rname] = rconfig.get(CONF_DEVICES)
 
     # Create server thread
     bound_system_callback = partial(_system_callback_handler, hass, config)
@@ -295,9 +293,8 @@ def setup(hass, config):
 
     # Init homematic hubs
     entity_hubs = []
-    for _, hub_data in hosts.items():
+    for hub_name in conf[CONF_HOSTS].keys():
-        entity_hubs.append(HMHub(
+        entity_hubs.append(HMHub(hass, homematic, hub_name))
-            hass, homematic, hub_data[CONF_NAME], hub_data[CONF_VARIABLES]))
 
     # Register HomeMatic services
     descriptions = load_yaml_config_file(
@@ -331,8 +328,7 @@ def setup(hass, config):
 
     hass.services.register(
         DOMAIN, SERVICE_VIRTUALKEY, _hm_service_virtualkey,
-        descriptions[DOMAIN][SERVICE_VIRTUALKEY],
+        descriptions[SERVICE_VIRTUALKEY], schema=SCHEMA_SERVICE_VIRTUALKEY)
-        schema=SCHEMA_SERVICE_VIRTUALKEY)
 
     def _service_handle_value(service):
         """Service to call setValue method for HomeMatic system variable."""
@@ -354,9 +350,9 @@ def setup(hass, config):
             hub.hm_set_variable(name, value)
 
     hass.services.register(
-        DOMAIN, SERVICE_SET_VAR_VALUE, _service_handle_value,
+        DOMAIN, SERVICE_SET_VARIABLE_VALUE, _service_handle_value,
-        descriptions[DOMAIN][SERVICE_SET_VAR_VALUE],
+        descriptions[SERVICE_SET_VARIABLE_VALUE],
-        schema=SCHEMA_SERVICE_SET_VAR_VALUE)
+        schema=SCHEMA_SERVICE_SET_VARIABLE_VALUE)
 
     def _service_handle_reconnect(service):
         """Service to reconnect all HomeMatic hubs."""
@@ -364,8 +360,7 @@ def setup(hass, config):
 
     hass.services.register(
         DOMAIN, SERVICE_RECONNECT, _service_handle_reconnect,
-        descriptions[DOMAIN][SERVICE_RECONNECT],
+        descriptions[SERVICE_RECONNECT], schema=SCHEMA_SERVICE_RECONNECT)
-        schema=SCHEMA_SERVICE_RECONNECT)
 
     def _service_handle_device(service):
         """Service to call setValue method for HomeMatic devices."""
@@ -383,9 +378,9 @@ def setup(hass, config):
         hmdevice.setValue(param, value, channel)
 
     hass.services.register(
-        DOMAIN, SERVICE_SET_DEV_VALUE, _service_handle_device,
+        DOMAIN, SERVICE_SET_DEVICE_VALUE, _service_handle_device,
-        descriptions[DOMAIN][SERVICE_SET_DEV_VALUE],
+        descriptions[SERVICE_SET_DEVICE_VALUE],
-        schema=SCHEMA_SERVICE_SET_DEV_VALUE)
+        schema=SCHEMA_SERVICE_SET_DEVICE_VALUE)
 
     return True
 
@@ -395,10 +390,10 @@ def _system_callback_handler(hass, config, src, *args):
     # New devices available at hub
     if src == 'newDevices':
         (interface_id, dev_descriptions) = args
-        proxy = interface_id.split('-')[-1]
+        interface = interface_id.split('-')[-1]
 
         # Device support active?
-        if not hass.data[DATA_DEVINIT][proxy]:
+        if not hass.data[DATA_CONF][interface]['connect']:
             return
 
         addresses = []
@@ -410,9 +405,9 @@ def _system_callback_handler(hass, config, src, *args):
 
         # Register EVENTS
         # Search all devices with an EVENTNODE that includes data
-        bound_event_callback = partial(_hm_event_handler, hass, proxy)
+        bound_event_callback = partial(_hm_event_handler, hass, interface)
         for dev in addresses:
-            hmdevice = hass.data[DATA_HOMEMATIC].devices[proxy].get(dev)
+            hmdevice = hass.data[DATA_HOMEMATIC].devices[interface].get(dev)
 
             if hmdevice.EVENTNODE:
                 hmdevice.setEventCallback(
@@ -429,7 +424,7 @@ def _system_callback_handler(hass, config, src, *args):
                     ('climate', DISCOVER_CLIMATE)):
                 # Get all devices of a specific type
                 found_devices = _get_devices(
-                    hass, discovery_type, addresses, proxy)
+                    hass, discovery_type, addresses, interface)
 
                 # When devices of this type are found
                 # they are setup in HASS and an discovery event is fired
@@ -448,12 +443,12 @@ def _system_callback_handler(hass, config, src, *args):
         })
 
 
-def _get_devices(hass, discovery_type, keys, proxy):
+def _get_devices(hass, discovery_type, keys, interface):
     """Get the HomeMatic devices for given discovery_type."""
     device_arr = []
 
     for key in keys:
-        device = hass.data[DATA_HOMEMATIC].devices[proxy][key]
+        device = hass.data[DATA_HOMEMATIC].devices[interface][key]
         class_name = device.__class__.__name__
         metadata = {}
 
@@ -485,7 +480,7 @@ def _get_devices(hass, discovery_type, keys, proxy):
                 device_dict = {
                     CONF_PLATFORM: "homematic",
                     ATTR_ADDRESS: key,
-                    ATTR_PROXY: proxy,
+                    ATTR_INTERFACE: interface,
                     ATTR_NAME: name,
                     ATTR_CHANNEL: channel
                 }
@@ -521,12 +516,12 @@ def _create_ha_name(name, channel, param, count):
         return "{} {} {}".format(name, channel, param)
 
 
-def _hm_event_handler(hass, proxy, device, caller, attribute, value):
+def _hm_event_handler(hass, interface, device, caller, attribute, value):
     """Handle all pyhomematic device events."""
     try:
         channel = int(device.split(":")[1])
         address = device.split(":")[0]
-        hmdevice = hass.data[DATA_HOMEMATIC].devices[proxy].get(address)
+        hmdevice = hass.data[DATA_HOMEMATIC].devices[interface].get(address)
     except (TypeError, ValueError):
         _LOGGER.error("Event handling channel convert error!")
         return
@@ -561,14 +556,14 @@ def _hm_event_handler(hass, proxy, device, caller, attribute, value):
 def _device_from_servicecall(hass, service):
     """Extract HomeMatic device from service call."""
     address = service.data.get(ATTR_ADDRESS)
-    proxy = service.data.get(ATTR_PROXY)
+    interface = service.data.get(ATTR_INTERFACE)
     if address == 'BIDCOS-RF':
         address = 'BidCoS-RF'
 
-    if proxy:
+    if interface:
-        return hass.data[DATA_HOMEMATIC].devices[proxy].get(address)
+        return hass.data[DATA_HOMEMATIC].devices[interface].get(address)
 
-    for _, devices in hass.data[DATA_HOMEMATIC].devices.items():
+    for devices in hass.data[DATA_HOMEMATIC].devices.values():
         if address in devices:
             return devices[address]
 
@@ -576,24 +571,22 @@ def _device_from_servicecall(hass, service):
 class HMHub(Entity):
     """The HomeMatic hub. (CCU2/HomeGear)."""
 
-    def __init__(self, hass, homematic, name, use_variables):
+    def __init__(self, hass, homematic, name):
         """Initialize HomeMatic hub."""
         self.hass = hass
         self.entity_id = "{}.{}".format(DOMAIN, name.lower())
         self._homematic = homematic
         self._variables = {}
         self._name = name
-        self._state = STATE_UNKNOWN
+        self._state = None
-        self._use_variables = use_variables
 
         # Load data
-        track_time_interval(
+        self.hass.helpers.event.track_time_interval(
-            self.hass, self._update_hub, SCAN_INTERVAL_HUB)
+            self._update_hub, SCAN_INTERVAL_HUB)
         self.hass.add_job(self._update_hub, None)
 
-        if self._use_variables:
+        self.hass.helpers.event.track_time_interval(
-            track_time_interval(
+            self._update_variables, SCAN_INTERVAL_VARIABLES)
-                self.hass, self._update_variables, SCAN_INTERVAL_VARIABLES)
         self.hass.add_job(self._update_variables, None)
 
     @property
@@ -672,7 +665,7 @@ class HMDevice(Entity):
         """Initialize a generic HomeMatic device."""
         self._name = config.get(ATTR_NAME)
         self._address = config.get(ATTR_ADDRESS)
-        self._proxy = config.get(ATTR_PROXY)
+        self._interface = config.get(ATTR_INTERFACE)
         self._channel = config.get(ATTR_CHANNEL)
         self._state = config.get(ATTR_PARAM)
         self._data = {}
@@ -700,11 +693,6 @@ class HMDevice(Entity):
         """Return the name of the device."""
         return self._name
 
-    @property
-    def assumed_state(self):
-        """Return true if unable to access real state of the device."""
-        return not self._available
-
     @property
     def available(self):
         """Return true if device is available."""
@@ -728,7 +716,7 @@ class HMDevice(Entity):
 
         # Static attributes
         attr['id'] = self._hmdevice.ADDRESS
-        attr['proxy'] = self._proxy
+        attr['interface'] = self._interface
 
         return attr
 
@@ -739,7 +727,8 @@ class HMDevice(Entity):
 
         # Initialize
         self._homematic = self.hass.data[DATA_HOMEMATIC]
-        self._hmdevice = self._homematic.devices[self._proxy][self._address]
+        self._hmdevice = \
+            self._homematic.devices[self._interface][self._address]
         self._connected = True
 
         try:

homeassistant/components/homematic/services.yaml

@@ -0,0 +1,52 @@
+# Describes the format for available component services
+
+virtualkey:
+  description: Press a virtual key from CCU/Homegear or simulate keypress.
+  fields:
+    address:
+      description: Address of homematic device or BidCoS-RF for virtual remote.
+      example: BidCoS-RF
+    channel:
+      description: Channel for calling a keypress.
+      example: 1
+    param:
+      description: Event to send i.e. PRESS_LONG, PRESS_SHORT.
+      example: PRESS_LONG
+    interface:
+      description: (Optional) for set a hosts value.
+      example: Hosts name from config
+
+set_variable_value:
+  description: Set the name of a node.
+  fields:
+    entity_id:
+      description: Name(s) of homematic central to set value.
+      example: 'homematic.ccu2'
+    name:
+      description: Name of the variable to set.
+      example: 'testvariable'
+    value:
+      description: New value
+      example: 1
+
+set_device_value:
+  description: Set a device property on RPC XML interface.
+  fields:
+    address:
+      description: Address of homematic device or BidCoS-RF for virtual remote
+      example: BidCoS-RF
+    channel:
+      description: Channel for calling a keypress
+      example: 1
+    param:
+      description: Event to send i.e. PRESS_LONG, PRESS_SHORT
+      example: PRESS_LONG
+    interface:
+      description: (Optional) for set a hosts value
+      example: Hosts name from config
+    value:
+      description: New value
+      example: 1
+
+reconnect:
+  description: Reconnect to all Homematic Hubs.

homeassistant/components/services.yaml

@@ -32,55 +32,6 @@ foursquare:
         description: Vertical accuracy of the user's location, in meters.
         example: 1
 
-homematic:
-  virtualkey:
-    description: Press a virtual key from CCU/Homegear or simulate keypress.
-    fields:
-      address:
-        description: Address of homematic device or BidCoS-RF for virtual remote.
-        example: BidCoS-RF
-      channel:
-        description: Channel for calling a keypress.
-        example: 1
-      param:
-        description: Event to send i.e. PRESS_LONG, PRESS_SHORT.
-        example: PRESS_LONG
-      proxy:
-        description: (Optional) for set a hosts value.
-        example: Hosts name from config
-  set_var_value:
-    description: Set the name of a node.
-    fields:
-      entity_id:
-        description: Name(s) of homematic central to set value.
-        example: 'homematic.ccu2'
-      name:
-        description: Name of the variable to set.
-        example: 'testvariable'
-      value:
-        description: New value
-        example: 1
-  set_dev_value:
-    description: Set a device property on RPC XML interface.
-    fields:
-      address:
-        description: Address of homematic device or BidCoS-RF for virtual remote
-        example: BidCoS-RF
-      channel:
-        description: Channel for calling a keypress
-        example: 1
-      param:
-        description: Event to send i.e. PRESS_LONG, PRESS_SHORT
-        example: PRESS_LONG
-      proxy:
-        description: (Optional) for set a hosts value
-        example: Hosts name from config
-      value:
-        description: New value
-        example: 1
-  reconnect:
-    description: Reconnect to all Homematic Hubs.
-
 microsoft_face:
   create_group:
     description: Create a new person group.