Add some how-to guides

Author: GDYendell

docs/how-to/arrange-epics-screens.md

@@ -0,0 +1,84 @@
+# Arrange EPICS Screens with Groups and Sub-Controllers
+
+This guide shows how to use `group` on attributes and commands to organise widgets into
+labelled boxes on a screen, and how splitting a device into sub-controllers creates
+navigable sub-screens for larger devices.
+
+Both the CA and PVA EPICS transports generate screens from the same controller structure,
+so the techniques shown here apply to both.
+
+## Group Attributes and Commands into Boxes
+
+By default, all attributes and commands on a controller appear as a flat list of widgets
+on the generated screen. Assigning a `group` string places them together inside a labelled
+box.
+
+```python
+from fastcs.attributes import AttrR, AttrRW
+from fastcs.controllers import Controller
+from fastcs.datatypes import Float, Int
+from fastcs.methods import command
+
+
+class PowerSupplyController(Controller):
+    voltage = AttrRW(Float(), group="Output")
+    current = AttrRW(Float(), group="Output")
+    power = AttrR(Float(), group="Output")
+
+    temperature = AttrR(Float(), group="Status")
+    fault_code = AttrR(Int(), group="Status")
+
+    @command(group="Actions")
+    async def reset_faults(self) -> None:
+        ...
+
+    @command(group="Actions")
+    async def enable_output(self) -> None:
+        ...
+```
+
+The generated screen will show three boxes — **Output**, **Status**, and **Actions** —
+each containing only the widgets assigned to that group. Attributes and commands with no
+`group` are placed outside any box, directly on the screen.
+
+## Use Sub-Controllers to Create Sub-Screens
+
+For devices with many attributes, a single flat screen becomes unwieldy. Splitting
+functionality across multiple controllers, connected with `add_sub_controller()`, causes
+the transport to generate a top-level screen with navigation links to per-sub-controller
+sub-screens.
+
+```python
+from fastcs.attributes import AttrR, AttrRW
+from fastcs.controllers import Controller
+from fastcs.datatypes import Float, Int
+from fastcs.methods import command
+
+
+class ChannelController(Controller):
+    voltage = AttrRW(Float(), group="Output")
+    current = AttrRW(Float(), group="Output")
+    temperature = AttrR(Float(), group="Status")
+
+    @command(group="Actions")
+    async def enable(self) -> None:
+        ...
+
+
+class MultiChannelPSU(Controller):
+    total_power = AttrR(Float())
+
+    @command()
+    async def disable_all(self) -> None:
+        ...
+
+    def __init__(self, num_channels: int) -> None:
+        super().__init__()
+        for i in range(1, num_channels + 1):
+            self.add_sub_controller(f"Ch{i:02d}", ChannelController())
+```
+
+The top-level screen for `MultiChannelPSU` shows `TotalPower` and `DisableAll` alongside
+buttons labelled **Ch01**, **Ch02**, … that each open the sub-screen for that channel.
+Each channel sub-screen then shows the **Output**, **Status**, and **Actions** boxes
+defined on `ChannelController`.

docs/how-to/launch-framework.md

@@ -0,0 +1,177 @@
+# Use the Launch Framework for CLI Applications
+
+This guide shows how to use `launch()` to create deployable FastCS drivers with
+automatic CLI generation and YAML configuration.
+
+## Basic Setup
+
+The `launch()` function generates a CLI from the controller's type hints:
+
+```python
+from fastcs.controllers import Controller
+from fastcs.launch import launch
+
+class MyController(Controller):
+    pass
+
+if __name__ == "__main__":
+    launch(MyController)
+```
+
+This creates a CLI with:
+
+- `--version` - Display version information
+- `schema` - Output JSON schema for configuration
+- `run <config.yaml>` - Start the controller with a YAML config file
+
+## Adding Configuration Options
+
+It is recommended to use a dataclass or Pydantic model for the controller's
+configuration, as these provide schema generation and IDE support. The `launch()`
+function checks that `__init__` has at most one argument (besides `self`) and that the
+argument has a type hint, which is required to infer the schema:
+
+```python
+from dataclasses import dataclass
+
+from fastcs.controllers import Controller
+from fastcs.launch import launch
+
+@dataclass
+class DeviceSettings:
+    ip_address: str
+    port: int = 25565
+    timeout: float = 5.0
+
+class DeviceController(Controller):
+    def __init__(self, settings: DeviceSettings):
+        super().__init__()
+        self.settings = settings
+
+if __name__ == "__main__":
+    launch(DeviceController, version="1.0.0")
+```
+
+## YAML Configuration Files
+
+Create a YAML configuration file matching the schema:
+
+```yaml
+# device_config.yaml
+controller:
+  ip_address: "192.168.1.100"
+  port: 25565
+  timeout: 10.0
+
+transport:
+  - epicsca:
+      pv_prefix: "DEVICE"
+```
+
+Run with:
+
+```bash
+python my_driver.py run device_config.yaml
+```
+
+## Schema Generation
+
+Generate JSON schema for the configuration yaml:
+
+```bash
+python my_driver.py schema > schema.json
+```
+
+Use this schema for IDE autocompletion in YAML files:
+
+```yaml
+# yaml-language-server: $schema=schema.json
+controller:
+  ip_address: "192.168.1.100"
+  # ... IDE will provide autocompletion
+```
+
+## Transport Configuration
+
+Transports are configured in the `transport` section as a list:
+
+```yaml
+transport:
+  # EPICS Channel Access
+  - epicsca:
+      pv_prefix: "DEVICE"
+    gui:
+      output_path: "opis/device.bob"
+      title: "Device Control"
+
+  # REST API
+  - rest:
+      host: "0.0.0.0"
+      port: 8080
+
+  # GraphQL
+  - graphql:
+      host: "localhost"
+      port: 8081
+```
+
+## Logging Options
+
+The `run` command includes logging options:
+
+```bash
+# Set log level
+python my_driver.py run config.yaml --log-level debug
+
+# Send logs to Graylog
+python my_driver.py run config.yaml \
+  --graylog-endpoint "graylog.example.com:12201" \
+  --graylog-static-fields "app=my_driver,env=prod"
+```
+
+Available log levels: `TRACE`, `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
+
+## Version Information
+
+Pass a version string to display the driver version:
+
+```python
+launch(DeviceController, version="1.2.3")
+```
+
+```bash
+$ python my_driver.py --version
+DeviceController: 1.2.3
+FastCS: 0.12.0
+```
+
+## Constraints
+
+The `launch()` function requires:
+
+1. Controller `__init__` must have at most 2 arguments (including `self`)
+2. If a configuration argument exists, it must have a type hint
+
+Using a dataclass or Pydantic model is recommended for the configuration type, as it enables JSON schema generation. Other type-hinted types will work, but will not produce a useful schema.
+
+```python
+# Valid - no config
+class SimpleController(Controller):
+    def __init__(self):
+        super().__init__()
+
+# Valid - with config
+class ConfiguredController(Controller):
+    def __init__(self, settings: MySettings):
+        super().__init__()
+
+# Invalid - missing type hint
+class BadController(Controller):
+    def __init__(self, settings):  # Error: no type hint
+        super().__init__()
+
+# Invalid - too many arguments
+class TooManyArgs(Controller):
+    def __init__(self, settings: MySettings, extra: str):  # Error
+        super().__init__()
+```