Refactor documentation for action groups and executions; clarify command execution details and improve method docstrings

Author: iMicknl

docs/core-concepts.md

@@ -8,37 +8,73 @@ A server describes where the API calls go. A gateway is the physical hub in your
 
 The setup describes the current gateway configuration and device inventory. Devices expose metadata like `uiClass` and `widget`, plus a list of current `states`.
 
-## Actions, action groups, and commands
+## Commands, actions, and action groups
 
-Commands are sent as `Action` objects, grouped into an action group. Each action targets a device URL and a set of commands with parameters.
+The Overkiz API uses a three-level hierarchy to control devices:
+
+- **Command** — A single instruction for a device, like `open`, `close`, or `setClosure(50)`. A command has a name and optional parameters.
+- **Action** — One or more commands targeting a **single device** (identified by its device URL). The gateway allows at most one action per device in each action group.
+- **Action group** — A batch of actions submitted to the gateway as a single execution. An action group can target multiple devices at once.
+
+```
+ActionGroup
+├── Action (device A)
+│   ├── Command("open")
+│   └── Command("setClosure", [50])
+└── Action (device B)
+    └── Command("close")
+```
+
+Action groups come in two flavors:
+
+- **Ad-hoc** — Built on the fly from `Action` and `Command` objects and executed via `execute_action_group()`.
+- **Persisted** — Stored on the server (like saved scenes). Retrieved with `get_action_groups()` and executed by OID via `execute_persisted_action_group()`, or scheduled for a future timestamp via `schedule_persisted_action_group()`.
+
+## Executions
+
+When an action group is submitted, the server returns an `exec_id` identifying the **execution**. An execution tracks the lifecycle of a submitted action group — from queued, to running, to completed or failed.
+
+- **Track** running executions with `get_current_executions()` or `get_current_execution(exec_id)`.
+- **Cancel** a running execution with `cancel_execution(exec_id)`.
+- **Review** past results with `get_execution_history()`.
+
+Executions run asynchronously on the gateway. State changes are delivered through events, so you typically combine execution with an event listener to know when commands finish.
+
+## Execution modes
+
+An optional `ExecutionMode` can be passed when executing an action group:
+
+- `HIGH_PRIORITY` — Bypasses the normal execution queue.
+- `GEOLOCATED` — Triggered by geolocation rules.
+- `INTERNAL` — Used for internal/system executions.
 
 ## States
 
 States are name/value pairs that represent the current device status, such as closure position or temperature.
 
 ## Events and listeners
 
-The API uses an event listener that you register once per session. Fetching events drains the server-side buffer.
-
-## Execution model
-
-Commands are executed asynchronously by the platform. You can poll execution state via events or refresh device states after a delay.
+The API uses an event listener that you register once per session. Fetching events drains the server-side buffer. Events include execution state changes, device state updates, and other notifications.
 
 ## Relationship diagram
 
 ```
 Client
-  |
-  |-- Server (cloud or local)
-  |
-  |-- Gateway
-        |
-        |-- Setup
-        |     |
-        |     |-- Devices
-        |            |
-        |            |-- States
-        |            |-- Actions -> Commands -> Parameters
-        |
-        |-- Event Listener -> Events
+  │
+  ├── Server (cloud or local)
+  │
+  └── Gateway
+        │
+        ├── Setup
+        │     │
+        │     └── Devices
+        │           │
+        │           ├── States (name/value pairs)
+        │           └── Actions ──► Commands ──► Parameters
+        │
+        ├── Action Groups (persisted)
+        │
+        ├── Executions (running action groups)
+        │
+        └── Event Listener ──► Events
 ```

docs/device-control.md

@@ -142,61 +142,138 @@ if device.identifier.is_sub_device:
     print(f"Sub-device ID: {device.identifier.subsystem_id}")
 ```
 
-## Send a command
+## Send a single command to a device
+
+Create an `Action` with the target device URL and one or more `Command` objects, then wrap it in an action group. The method returns an `exec_id` you can use to track or cancel the execution.
 
 ```python
 from pyoverkiz.enums import OverkizCommand
 from pyoverkiz.models import Action, Command
 
-await client.execute_action_group(
+exec_id = await client.execute_action_group(
     actions=[
         Action(
             device_url="io://1234-5678-1234/12345678",
             commands=[
-                Command(
-                    name=OverkizCommand.SET_CLOSURE,
-                    parameters=[50],
-                )
+                Command(name=OverkizCommand.SET_CLOSURE, parameters=[50])
             ],
         )
-        ],
-    label="Execution: set closure",
+    ],
+    label="Set closure to 50%",
 )
 ```
 
-## Action groups and common patterns
+## Send multiple commands to one device
 
-- Use a single action group to batch multiple device commands.
+A single action can hold multiple commands. They are executed in order on the device.
 
 ```python
 from pyoverkiz.enums import OverkizCommand, OverkizCommandParam
 from pyoverkiz.models import Action, Command
 
-await client.execute_action_group(
+exec_id = await client.execute_action_group(
     actions=[
         Action(
             device_url="io://1234-5678-1234/12345678",
             commands=[
                 Command(
                     name=OverkizCommand.SET_DEROGATION,
                     parameters=[21.5, OverkizCommandParam.FURTHER_NOTICE],
-                )
-            ],
-        ),
-        Action(
-            device_url="io://1234-5678-1234/12345678",
-            commands=[
+                ),
                 Command(
                     name=OverkizCommand.SET_MODE_TEMPERATURE,
                     parameters=[OverkizCommandParam.MANUAL_MODE, 21.5],
-                )
+                ),
             ],
         )
     ],
-    label="Execution: multiple commands",
+    label="Set temperature derogation",
 )
 ```
 
+## Control multiple devices at once
+
+An action group can contain one action per device. All actions in the group are submitted as a single execution.
+
+```python
+from pyoverkiz.enums import OverkizCommand
+from pyoverkiz.models import Action, Command
+
+exec_id = await client.execute_action_group(
+    actions=[
+        Action(
+            device_url="io://1234-5678-1234/11111111",
+            commands=[Command(name=OverkizCommand.CLOSE)],
+        ),
+        Action(
+            device_url="io://1234-5678-1234/22222222",
+            commands=[Command(name=OverkizCommand.OPEN)],
+        ),
+    ],
+    label="Close blinds, open garage",
+)
+```
+
+!!! note
+    The gateway allows at most **one action per device** in each action group.
+    If you need to send commands to the same device in separate executions, use
+    separate `execute_action_group()` calls.
+
+## Execution modes
+
+Pass an `ExecutionMode` to change how the gateway processes the action group:
+
+```python
+from pyoverkiz.enums import ExecutionMode, OverkizCommand
+from pyoverkiz.models import Action, Command
+
+exec_id = await client.execute_action_group(
+    actions=[
+        Action(
+            device_url="io://1234-5678-1234/12345678",
+            commands=[Command(name=OverkizCommand.OPEN)],
+        )
+    ],
+    mode=ExecutionMode.HIGH_PRIORITY,
+)
+```
+
+Available modes: `HIGH_PRIORITY`, `GEOLOCATED`, `INTERNAL`. When omitted, the default execution mode is used.
+
+## Track and cancel executions
+
+```python
+# List all running executions
+executions = await client.get_current_executions()
+
+# Get a specific execution
+execution = await client.get_current_execution(exec_id)
+
+# Cancel a running execution
+await client.cancel_execution(exec_id)
+
+# Review past executions
+history = await client.get_execution_history()
+```
+
+## Persisted action groups
+
+Action groups can be stored on the server (like saved scenes). Use these methods to list and execute them:
+
+```python
+# List all persisted action groups
+action_groups = await client.get_action_groups()
+
+for ag in action_groups:
+    print(f"{ag.label} (OID: {ag.oid})")
+
+# Execute a persisted action group by OID
+exec_id = await client.execute_persisted_action_group(ag.oid)
+
+# Schedule for future execution (Unix timestamp)
+trigger_id = await client.schedule_persisted_action_group(ag.oid, timestamp=1735689600)
+```
+
 ## Limitations and rate limits
 
 Gateways impose limits on how many executions can run or be queued simultaneously. If the execution queue is full, the API will raise an `ExecutionQueueFullError`. Most gateways allow up to 10 concurrent executions.

pyoverkiz/client.py

@@ -373,7 +373,7 @@ async def get_gateways(self, refresh: bool = False) -> list[Gateway]:
 
     @retry_on_auth_error
     async def get_execution_history(self) -> list[HistoryExecution]:
-        """List execution history."""
+        """List past executions and their outcomes."""
         response = await self._get("history/executions")
         return [HistoryExecution(**h) for h in decamelize(response)]
 
@@ -449,13 +449,13 @@ async def unregister_event_listener(self) -> None:
 
     @retry_on_auth_error
     async def get_current_execution(self, exec_id: str) -> Execution:
-        """Get an action group execution currently running."""
+        """Get a currently running execution by its exec_id."""
         response = await self._get(f"exec/current/{exec_id}")
         return Execution(**decamelize(response))
 
     @retry_on_auth_error
     async def get_current_executions(self) -> list[Execution]:
-        """Get all action groups executions currently running."""
+        """Get all currently running executions."""
         response = await self._get("exec/current")
         return [Execution(**e) for e in decamelize(response)]
 
@@ -492,34 +492,29 @@ async def execute_action_group(
         mode: ExecutionMode | None = None,
         label: str | None = "python-overkiz-api",
     ) -> str:
-        """Execute a non-persistent action group.
+        """Execute an ad-hoc action group built from the given actions.
 
-        When action queue is enabled, actions will be batched with other actions
-        executed within the configured delay window. The method will wait for the
-        batch to execute and return the exec_id.
+        An action group is a batch of device actions submitted as a single
+        execution. Each ``Action`` targets one device and contains one or more
+        ``Command`` instances (e.g. ``open``, ``setClosure(50)``). The gateway
+        allows at most one action per device per action group.
 
-        Gateways only allow a single action per device in each action group. The
-        action queue enforces this by merging commands for the same device into
-        a single action in the batch.
+        When the action queue is enabled, actions are held for a short delay
+        and merged with other actions submitted in the same window. Commands
+        targeting the same device are combined into a single action. The method
+        blocks until the batch executes and returns the resulting exec_id.
 
-        When action queue is disabled, executes immediately and returns exec_id.
-
-        The API is consistent regardless of queue configuration - always returns
-        exec_id string directly.
+        When the action queue is disabled, the action group is sent immediately.
 
         Args:
-            actions: List of actions to execute.
-            mode: Execution mode (`GEOLOCATED`, `INTERNAL`, `HIGH_PRIORITY`,
-                or `None`).
-            label: Label for the action group.
+            actions: One or more actions to execute. Each action targets a
+                single device and holds one or more commands.
+            mode: Optional execution mode (``HIGH_PRIORITY``, ``GEOLOCATED``,
+                or ``INTERNAL``).
+            label: Human-readable label for the execution.
 
         Returns:
-            The `exec_id` string from the executed action group.
-
-        Example:
-            ```python
-            exec_id = await client.execute_action_group([action])
-            ```
+            The ``exec_id`` identifying the execution on the server.
         """
         if self._action_queue:
             queued = await self._action_queue.add(actions, mode, label)
@@ -548,12 +543,12 @@ def get_pending_actions_count(self) -> int:
 
     @retry_on_auth_error
     async def cancel_execution(self, exec_id: str) -> None:
-        """Cancel a running setup-level execution."""
+        """Cancel a running execution by its exec_id."""
         await self._delete(f"exec/current/setup/{exec_id}")
 
     @retry_on_auth_error
     async def get_action_groups(self) -> list[ActionGroup]:
-        """List the persisted action groups."""
+        """List action groups persisted on the server."""
         response = await self._get("actionGroups")
         return [ActionGroup(**action_group) for action_group in decamelize(response)]
 
@@ -574,13 +569,13 @@ async def get_places(self) -> Place:
 
     @retry_on_auth_error
     async def execute_persisted_action_group(self, oid: str) -> str:
-        """Execute a persisted action group by its OID."""
+        """Execute a server-side action group by its OID (see ``get_action_groups``)."""
         response = await self._post(f"exec/{oid}")
         return cast(str, response["execId"])
 
     @retry_on_auth_error
     async def schedule_persisted_action_group(self, oid: str, timestamp: int) -> str:
-        """Schedule a persisted action group for future execution."""
+        """Schedule a server-side action group for execution at the given timestamp."""
         response = await self._post(f"exec/schedule/{oid}/{timestamp}")
         return cast(str, response["triggerId"])