Adapter rework for Zebra (#174)

This changes the way adapters work within tickit. This
attempts unifies the adapters in a composed way by seperating out the IO
and the device specific handling logic. You now have an 
`AdapterContainer` which has both an `adapter`, the device specific part that handles
the message,  and the `io` which does the actual io logic.

The `AdapterContainer` acts as the previous adapters did and contains
the `run_forever` method. Now though, this calls a `setup` method in the
`io` in which the `io` takes the specific `adapter` that has been
provided. The `adapter` and `io` are failry coupled given the io needs a
specific adapter type to work, eg. `class
HttpIo(AdapterIo[HttpAdapter]): `. However hopefully this change
provides a clearer divide in developer and user implemented code and
simplifies the life of the users.

As before users would need to write specific adapters for their devices
but this should simplifiy their lives a bit as all they now need is the
device and device specific methods. 

Most importantly, and the motivation for this change, is there is no
longer a limitation on what an adapter may apply to. This allows us to
write an adapter which inspect the components in a system simulation
There is an example which uses a tcpio and commandadapter.

Author: abbiemery

docs/user/explanations/adapters.rst

@@ -7,33 +7,28 @@ Adapters allow us to influence the device from outside the simulation, such as
 using a TCP client to alter a parameter on a device. A device may have multiple
 adapters simultaneously.
 
-There are four adapters included in the framework:
+Adapters are implemented within `AdapterContainer` and these containers are added
+to the device or system simulations. An AdapterContainer simply takes an adapter and
+an appropriate `AdapterIo`. When the container is run, it sets up the io with the 
+specific adapter.
 
-#. `Composed adapter`_
+- The Adapter contains the device specific interface for a given io type.
+- The `AdapterIo` contains IO logic which is agnositc to the details of the device.
+
+There are four adapter types included in the framework:
+
+#. `Command adapter`_
 #. `ZMQ adapter`_
 #. `HTTP adapter`_
 #. `EPICS adapter`_
 
-Composed adapter
-----------------
-The composed adapter acts to implement a server and an interpreter. It delegates
-the hosting of an external messaging protocol to a server and message handling
-to an interpreter.
-
-Tickit currently includes one server implementation, a TCP server, and one
-interpreter, the command interpreter.
 
-The command interpreter is a generic interpreter which identifies commands from
-incoming messages. Commands are defined via decoration of adapter methods and
-the only such command type currently is a `RegexCommand`. This matches incoming
-messages to regex patterns and processes the command appropriately.
-
-Tickit also includes three interpreter wrappers for the command interpreter.
-These wrap the command interpreter to allow for more complex message handling
-and can be used with the composed adapter in the same way.
-
-Users may implement their own servers and interpreters and then use the composed
-adapter to utilise them for the device.
+Command adapter
+----------------
+The command adapter identifies and handles commands from incoming messages and is 
+utilised with `TcpIo`. Commands are defined via decoration of adapter methods and the
+only such command type currently is a `RegexCommand`. This matches incoming messages to
+regex patterns and processes the command appropriately.
 
 
 ZMQ adapter
@@ -43,7 +38,7 @@ An adapter for use on a ZeroMQ data stream.
 
 HTTP adapter
 ------------
-An adapter that hosts an HTTP server, e.g. for devices with REST APIs.
+An adapter that utilises HTTP endpoints for the `HttpIo`.
 
 
 EPICS adapter

docs/user/explanations/system-simulation-adapters.rst

@@ -0,0 +1,152 @@
+System Simulation Adapters
+==========================
+
+Adapters may also be used with system simulations (`SystemSimulationComponent`),
+as well as with devices (`DeviceSimulation`). This would allow you, for example, to
+query what device components are inside the system simulation component, and how they
+are wired together.
+
+Currently system adapters need both wiring and components. There is a helper base class
+for implementing this.  
+
+.. code-block:: python
+        
+    class BaseSystemSimulationAdapter:
+        """A base for a SystemSimulationComponent adapter."""
+
+        _components: Dict[ComponentID, Component]
+        _wiring: Union[Wiring, InverseWiring]
+
+        def setup_adapter(
+            self,
+            components: Dict[ComponentID, Component],
+            wiring: Union[Wiring, InverseWiring],
+        ) -> None:
+            """Provides the components and wiring of a SystemSimulationComponent."""
+            self._components = components
+            self._wiring = wiring
+
+
+
+Nested Amplifier Example
+------------------------
+
+The following system adapter is a simple `CommandAdapter`. This Can be used to query the
+SystemSimulationComponent for a list of ID's of the components it contains; and to
+return the wiring map of the components.
+
+.. code-block:: python
+
+    class SystemSimulationAdapter(BaseSystemSimulationAdapter, CommandAdapter):
+
+        _byte_format: ByteFormat = ByteFormat(b"%b\r\n")
+
+        @RegexCommand(r"ids", False, "utf-8")
+        async def get_component_ids(self) -> bytes:
+            """Returns a list of ids for all the components in the system simulation."""
+            return str(self._components.keys()).encode("utf-8")
+
+        @RegexCommand(r"wiring", False, "utf-8")
+        async def get_wiring(self) -> bytes:
+            """Returns the wiring object used by the nested scheduler."""
+            return str(self._wiring).encode("utf-8")
+
+To use this adapter we would need to put it in an adapter container with TcpIo and
+assign it as an argument in the SystemSimulationComponent.
+
+.. code-block:: python
+
+    @pydantic.v1.dataclasses.dataclass
+    class NestedAmplifierWithAdapter(ComponentConfig):
+        """Simulation of a nested amplifier with a CommandAdapter."""
+
+        name: ComponentID
+        inputs: Dict[PortID, ComponentPort]
+        components: List[ComponentConfig]
+        expose: Dict[PortID, ComponentPort]
+
+        def __call__(self) -> Component:  # noqa: D102
+            return SystemSimulationComponent(
+                name=self.name,
+                components=self.components,
+                expose=self.expose,
+                adapter=AdapterContainer(
+                    SystemSimulationAdapter(),
+                    TcpIo(host="localhost", port=25560),
+                ),
+            )
+
+
+
+This ComponentConfig ``NestedAmplifierWithAdapter`` can be used as any other component.
+
+Below is a very simple simulation with a system simulation component. It is a
+source, which is connected to a `SystemSimulationComponent` which only contains a
+single amplifier. The output of this amplfier is fed to the output of the system
+simulation component, which is wired to a sink. 
+
+
+.. code-block:: yaml
+
+  - type: tickit.devices.source.Source
+    name: source
+    inputs: {}
+    value: 10.0
+  - type: examples.adapters.system_simulation_adapter_config.NestedAmplifierWithAdapter
+    name: nested-amp
+    inputs:
+        input_1:
+        component: source
+        port: value
+    components:
+        - type: examples.devices.amplifier.Amplifier
+        name: amp
+        inputs:
+            initial_signal:
+            component: external
+            port: input_1
+        initial_amplification: 2
+    expose:
+        output_1:
+        component: amp
+        port: amplified_signal
+  - type: tickit.devices.sink.Sink
+    name: external_sink
+    inputs:
+        sink_1:
+        component: nested-amp
+        port: output_1
+
+
+
+Interacting with devices using a system simulation adapter
+----------------------------------------------------------
+
+When using a system adapter you must be careful to achieve the behaviour you desire.
+
+If you wish to write to and change the devices within the system simulation then any
+change you make must be followed by raising an interrupt in that specific device
+component. If you do not, the changes will not propagate correctly.
+
+This is done below in the ``raise_component_interrupt`` method which takes a given
+component ID and does ``await component.raise_interrupt()`` for the specific component.
+
+
+.. code-block:: python
+
+    class SystemSimulationAdapter(BaseSystemSimulationAdapter, CommandAdapter):
+
+        _byte_format: ByteFormat = ByteFormat(b"%b\r\n")
+
+        @RegexCommand(r"interrupt=(\w+)", False, "utf-8")
+            async def raise_component_interrupt(self, id: str) -> bytes:
+                """Raises an interrupt in the component of the given id."""
+                component = self._components.get(ComponentID(id), None)
+
+                if isinstance(component, BaseComponent):
+                    await component.raise_interrupt()
+                    return str(f"Raised Interupt in {component.name}").encode("utf-8")
+                else:
+                    return str("ComponentID not recognised, No interupt raised.").encode(
+                        "utf-8"
+                    )