Multi-controller foundation: Controller.id, multi-class launch, unified transports, REST per-id (#353)

docs/how-to/launch-framework.md

@@ -58,16 +58,20 @@ Create a YAML configuration file matching the schema:
 
 ```yaml
 # device_config.yaml
-controller:
-  ip_address: "192.168.1.100"
-  port: 25565
-  timeout: 10.0
+controllers:
+  DEVICE:
+    controller:
+      ip_address: "192.168.1.100"
+      port: 25565
+      timeout: 10.0
 
 transport:
-  - epicsca:
-      pv_prefix: "DEVICE"
+  - epicsca: {}
 ```
 
+The key under `controllers:` (here `DEVICE`) is the controller id, used
+verbatim as the EPICS PV prefix and as the REST route prefix.
+
 Run with:
 
 ```bash
@@ -98,8 +102,7 @@ Transports are configured in the `transport` section as a list:
 ```yaml
 transport:
   # EPICS Channel Access
-  - epicsca:
-      pv_prefix: "DEVICE"
+  - epicsca: {}
     gui:
       output_path: "opis/device.bob"
       title: "Device Control"

docs/how-to/multiple-transports.md

@@ -10,17 +10,17 @@ Pass a list of transports to `FastCS`:
 from fastcs.control_system import FastCS
 from fastcs.transports import (
     EpicsCATransport,
-    EpicsIOCOptions,
     GraphQLTransport,
     RestTransport,
 )
 
 controller = MyController()
+controller.set_id("DEVICE")  # PV prefix for EPICS / route prefix for REST
 
 fastcs = FastCS(
     controller,
     [
-        EpicsCATransport(epicsca=EpicsIOCOptions(pv_prefix="DEVICE")),
+        EpicsCATransport(),
         RestTransport(),
         GraphQLTransport(),
     ]
@@ -30,6 +30,25 @@ fastcs.run()
 
 All transports run concurrently, exposing the same controller API.
 
+## Choosing controller ids across transports
+
+Each transport derives its addressing from the controller's id (the PV prefix
+for EPICS, the URL prefix for REST, the top-level Query field for GraphQL),
+and each enforces its own charset at startup.
+
+| Transport | Allowed id charset |
+|-----------|--------------------|
+| EPICS CA  | `[A-Za-z0-9_-]+`, plus the 60-char PV name limit |
+| EPICS PVA | `[A-Za-z0-9_-]+` |
+| REST      | `[A-Za-z0-9_-]+` |
+| GraphQL   | `[A-Za-z_][A-Za-z0-9_]*` (GraphQL `Name`: no hyphens, no leading digit) |
+
+If you serve the same controller through multiple transports, use the
+intersection — a leading letter or underscore followed by letters, digits and
+underscores. GraphQL is the lowest common denominator: an id like `dev-01`
+will start an EPICS or REST transport happily but fail fast when GraphQL is
+added.
+
 ## Available Transports
 
 | Transport | Protocol | Install Extra | Primary Use Case |
@@ -52,17 +71,18 @@ Each transport has its own options:
 
 ### EPICS Channel Access
 
+The PV prefix is the controller's id (set via `controller.set_id(...)` or
+auto-set by `launch()` from the YAML key).
+
 ```python
 from pathlib import Path
 from fastcs.transports import (
     EpicsCATransport,
     EpicsDocsOptions,
     EpicsGUIOptions,
-    EpicsIOCOptions,
 )
 
 epics_ca = EpicsCATransport(
-    epicsca=EpicsIOCOptions(pv_prefix="DEVICE"),
     gui=EpicsGUIOptions(
         output_path=Path(".") / "device.bob",
         title="Device Control",
@@ -76,11 +96,9 @@ epics_ca = EpicsCATransport(
 ### EPICS PV Access
 
 ```python
-from fastcs.transports import EpicsPVATransport, EpicsIOCOptions
+from fastcs.transports import EpicsPVATransport
 
-epics_pva = EpicsPVATransport(
-    epicspva=EpicsIOCOptions(pv_prefix="DEVICE"),
-)
+epics_pva = EpicsPVATransport()
 ```
 
 ### REST
@@ -134,25 +152,24 @@ from pathlib import Path
 from fastcs.transports import (
     EpicsCATransport,
     EpicsGUIOptions,
-    EpicsIOCOptions,
     EpicsPVATransport,
 )
 
+controller.set_id("DEVICE")
+
 fastcs = FastCS(
     controller,
     [
         EpicsCATransport(
-            epicsca=EpicsIOCOptions(pv_prefix="DEVICE"),
             gui=EpicsGUIOptions(output_path=Path(".") / "device.bob"),
         ),
-        EpicsPVATransport(
-            epicspva=EpicsIOCOptions(pv_prefix="DEVICE"),
-        ),
+        EpicsPVATransport(),
     ]
 )
 ```
 
-Both transports share the same PV prefix and expose identical PVs.
+Both transports derive the same PV prefix from the controller's id and
+expose identical PVs.
 
 ## YAML Configuration
 

docs/snippets/dynamic.py

@@ -16,7 +16,6 @@
 from fastcs.controllers import Controller
 from fastcs.datatypes import Bool, DataType, Float, Int, String
 from fastcs.launch import FastCS
-from fastcs.transports.epics import EpicsIOCOptions
 from fastcs.transports.epics.ca import EpicsCATransport
 
 
@@ -139,7 +138,7 @@ async def initialise(self):
         await self._connection.close()
 
 
-epics_ca = EpicsCATransport(epicsca=EpicsIOCOptions(pv_prefix="DEMO"))
+epics_ca = EpicsCATransport()
 connection_settings = IPConnectionSettings("localhost", 25565)
 fastcs = FastCS(TemperatureController(connection_settings), [epics_ca])
 

docs/snippets/static04.py

@@ -2,15 +2,14 @@
 from fastcs.controllers import Controller
 from fastcs.datatypes import String
 from fastcs.launch import FastCS
-from fastcs.transports.epics import EpicsIOCOptions
 from fastcs.transports.epics.ca.transport import EpicsCATransport
 
 
 class TemperatureController(Controller):
     device_id = AttrR(String())
 
 
-epics_ca = EpicsCATransport(epicsca=EpicsIOCOptions(pv_prefix="DEMO"))
+epics_ca = EpicsCATransport()
 fastcs = FastCS(TemperatureController(), [epics_ca])
 
 if __name__ == "__main__":

docs/snippets/static05.py

@@ -4,7 +4,7 @@
 from fastcs.controllers import Controller
 from fastcs.datatypes import String
 from fastcs.launch import FastCS
-from fastcs.transports.epics import EpicsGUIOptions, EpicsIOCOptions
+from fastcs.transports.epics import EpicsGUIOptions
 from fastcs.transports.epics.ca import EpicsCATransport
 
 
@@ -15,7 +15,7 @@ class TemperatureController(Controller):
 gui_options = EpicsGUIOptions(
     output_path=Path(".") / "demo.bob", title="Demo Temperature Controller"
 )
-epics_ca = EpicsCATransport(gui=gui_options, epicsca=EpicsIOCOptions(pv_prefix="DEMO"))
+epics_ca = EpicsCATransport(gui=gui_options)
 fastcs = FastCS(TemperatureController(), [epics_ca])
 
 if __name__ == "__main__":

docs/snippets/static06.py

@@ -5,7 +5,7 @@
 from fastcs.controllers import Controller
 from fastcs.datatypes import String
 from fastcs.launch import FastCS
-from fastcs.transports.epics import EpicsGUIOptions, EpicsIOCOptions
+from fastcs.transports.epics import EpicsGUIOptions
 from fastcs.transports.epics.ca import EpicsCATransport
 
 
@@ -25,7 +25,7 @@ async def connect(self):
 gui_options = EpicsGUIOptions(
     output_path=Path(".") / "demo.bob", title="Demo Temperature Controller"
 )
-epics_ca = EpicsCATransport(gui=gui_options, epicsca=EpicsIOCOptions(pv_prefix="DEMO"))
+epics_ca = EpicsCATransport(gui=gui_options)
 connection_settings = IPConnectionSettings("localhost", 25565)
 fastcs = FastCS(TemperatureController(connection_settings), [epics_ca])
 

docs/snippets/static07.py

@@ -7,7 +7,7 @@
 from fastcs.controllers import Controller
 from fastcs.datatypes import String
 from fastcs.launch import FastCS
-from fastcs.transports.epics import EpicsGUIOptions, EpicsIOCOptions
+from fastcs.transports.epics import EpicsGUIOptions
 from fastcs.transports.epics.ca import EpicsCATransport
 
 NumberT = TypeVar("NumberT", int, float)
@@ -47,7 +47,7 @@ async def connect(self):
 gui_options = EpicsGUIOptions(
     output_path=Path(".") / "demo.bob", title="Demo Temperature Controller"
 )
-epics_ca = EpicsCATransport(gui=gui_options, epicsca=EpicsIOCOptions(pv_prefix="DEMO"))
+epics_ca = EpicsCATransport(gui=gui_options)
 connection_settings = IPConnectionSettings("localhost", 25565)
 fastcs = FastCS(TemperatureController(connection_settings), [epics_ca])
 

docs/snippets/static08.py

@@ -7,7 +7,7 @@
 from fastcs.controllers import Controller
 from fastcs.datatypes import Float, String
 from fastcs.launch import FastCS
-from fastcs.transports.epics import EpicsGUIOptions, EpicsIOCOptions
+from fastcs.transports.epics import EpicsGUIOptions
 from fastcs.transports.epics.ca import EpicsCATransport
 
 NumberT = TypeVar("NumberT", int, float)
@@ -53,7 +53,7 @@ async def connect(self):
 gui_options = EpicsGUIOptions(
     output_path=Path(".") / "demo.bob", title="Demo Temperature Controller"
 )
-epics_ca = EpicsCATransport(gui=gui_options, epicsca=EpicsIOCOptions(pv_prefix="DEMO"))
+epics_ca = EpicsCATransport(gui=gui_options)
 connection_settings = IPConnectionSettings("localhost", 25565)
 fastcs = FastCS(TemperatureController(connection_settings), [epics_ca])
 

docs/snippets/static09.py

@@ -7,7 +7,7 @@
 from fastcs.controllers import Controller
 from fastcs.datatypes import Float, String
 from fastcs.launch import FastCS
-from fastcs.transports.epics import EpicsGUIOptions, EpicsIOCOptions
+from fastcs.transports.epics import EpicsGUIOptions
 from fastcs.transports.epics.ca import EpicsCATransport
 
 NumberT = TypeVar("NumberT", int, float)
@@ -60,7 +60,7 @@ async def connect(self):
 gui_options = EpicsGUIOptions(
     output_path=Path(".") / "demo.bob", title="Demo Temperature Controller"
 )
-epics_ca = EpicsCATransport(gui=gui_options, epicsca=EpicsIOCOptions(pv_prefix="DEMO"))
+epics_ca = EpicsCATransport(gui=gui_options)
 connection_settings = IPConnectionSettings("localhost", 25565)
 fastcs = FastCS(TemperatureController(connection_settings), [epics_ca])
 

docs/snippets/static10.py

@@ -7,7 +7,7 @@
 from fastcs.controllers import Controller
 from fastcs.datatypes import Float, Int, String
 from fastcs.launch import FastCS
-from fastcs.transports.epics import EpicsGUIOptions, EpicsIOCOptions
+from fastcs.transports.epics import EpicsGUIOptions
 from fastcs.transports.epics.ca import EpicsCATransport
 
 NumberT = TypeVar("NumberT", int, float)
@@ -78,7 +78,7 @@ async def connect(self):
 gui_options = EpicsGUIOptions(
     output_path=Path(".") / "demo.bob", title="Demo Temperature Controller"
 )
-epics_ca = EpicsCATransport(gui=gui_options, epicsca=EpicsIOCOptions(pv_prefix="DEMO"))
+epics_ca = EpicsCATransport(gui=gui_options)
 connection_settings = IPConnectionSettings("localhost", 25565)
 fastcs = FastCS(TemperatureController(4, connection_settings), [epics_ca])
 

docs/snippets/static11.py

@@ -8,7 +8,7 @@
 from fastcs.controllers import Controller
 from fastcs.datatypes import Enum, Float, Int, String
 from fastcs.launch import FastCS
-from fastcs.transports.epics import EpicsGUIOptions, EpicsIOCOptions
+from fastcs.transports.epics import EpicsGUIOptions
 from fastcs.transports.epics.ca import EpicsCATransport
 
 NumberT = TypeVar("NumberT", int, float)
@@ -85,7 +85,7 @@ async def connect(self):
 gui_options = EpicsGUIOptions(
     output_path=Path(".") / "demo.bob", title="Demo Temperature Controller"
 )
-epics_ca = EpicsCATransport(gui=gui_options, epicsca=EpicsIOCOptions(pv_prefix="DEMO"))
+epics_ca = EpicsCATransport(gui=gui_options)
 connection_settings = IPConnectionSettings("localhost", 25565)
 fastcs = FastCS(TemperatureController(4, connection_settings), [epics_ca])
 

docs/snippets/static12.py

@@ -10,7 +10,7 @@
 from fastcs.datatypes import Enum, Float, Int, String
 from fastcs.launch import FastCS
 from fastcs.methods import scan
-from fastcs.transports.epics import EpicsGUIOptions, EpicsIOCOptions
+from fastcs.transports.epics import EpicsGUIOptions
 from fastcs.transports.epics.ca import EpicsCATransport
 
 NumberT = TypeVar("NumberT", int, float)
@@ -98,7 +98,7 @@ async def update_voltages(self):
 gui_options = EpicsGUIOptions(
     output_path=Path(".") / "demo.bob", title="Demo Temperature Controller"
 )
-epics_ca = EpicsCATransport(gui=gui_options, epicsca=EpicsIOCOptions(pv_prefix="DEMO"))
+epics_ca = EpicsCATransport(gui=gui_options)
 connection_settings = IPConnectionSettings("localhost", 25565)
 fastcs = FastCS(TemperatureController(4, connection_settings), [epics_ca])
 

docs/snippets/static13.py

@@ -11,7 +11,7 @@
 from fastcs.datatypes import Enum, Float, Int, String
 from fastcs.launch import FastCS
 from fastcs.methods import command, scan
-from fastcs.transports.epics import EpicsGUIOptions, EpicsIOCOptions
+from fastcs.transports.epics import EpicsGUIOptions
 from fastcs.transports.epics.ca import EpicsCATransport
 
 NumberT = TypeVar("NumberT", int, float)
@@ -106,7 +106,7 @@ async def disable_all(self) -> None:
 gui_options = EpicsGUIOptions(
     output_path=Path(".") / "demo.bob", title="Demo Temperature Controller"
 )
-epics_ca = EpicsCATransport(gui=gui_options, epicsca=EpicsIOCOptions(pv_prefix="DEMO"))
+epics_ca = EpicsCATransport(gui=gui_options)
 connection_settings = IPConnectionSettings("localhost", 25565)
 fastcs = FastCS(TemperatureController(4, connection_settings), [epics_ca])
 

docs/snippets/static14.py

@@ -12,7 +12,7 @@
 from fastcs.launch import FastCS
 from fastcs.logging import configure_logging, logger
 from fastcs.methods import command, scan
-from fastcs.transports.epics import EpicsGUIOptions, EpicsIOCOptions
+from fastcs.transports.epics import EpicsGUIOptions
 from fastcs.transports.epics.ca import EpicsCATransport
 
 NumberT = TypeVar("NumberT", int, float)
@@ -112,7 +112,7 @@ async def disable_all(self) -> None:
 gui_options = EpicsGUIOptions(
     output_path=Path(".") / "demo.bob", title="Demo Temperature Controller"
 )
-epics_ca = EpicsCATransport(gui=gui_options, epicsca=EpicsIOCOptions(pv_prefix="DEMO"))
+epics_ca = EpicsCATransport(gui=gui_options)
 connection_settings = IPConnectionSettings("localhost", 25565)
 logger.info("Configuring connection settings", connection_settings=connection_settings)
 fastcs = FastCS(TemperatureController(4, connection_settings), [epics_ca])

docs/snippets/static15.py

@@ -12,7 +12,7 @@
 from fastcs.launch import FastCS
 from fastcs.logging import LogLevel, configure_logging, logger
 from fastcs.methods import command, scan
-from fastcs.transports.epics import EpicsGUIOptions, EpicsIOCOptions
+from fastcs.transports.epics import EpicsGUIOptions
 from fastcs.transports.epics.ca import EpicsCATransport
 
 NumberT = TypeVar("NumberT", int, float)
@@ -115,7 +115,7 @@ async def disable_all(self) -> None:
 gui_options = EpicsGUIOptions(
     output_path=Path(".") / "demo.bob", title="Demo Temperature Controller"
 )
-epics_ca = EpicsCATransport(gui=gui_options, epicsca=EpicsIOCOptions(pv_prefix="DEMO"))
+epics_ca = EpicsCATransport(gui=gui_options)
 connection_settings = IPConnectionSettings("localhost", 25565)
 logger.info("Configuring connection settings", connection_settings=connection_settings)
 fastcs = FastCS(TemperatureController(4, connection_settings), [epics_ca])