Added explanatory state diagram

README.md

@@ -102,3 +102,5 @@ You should get some log output about how this isn't safe to run in production -
 The REST API will present itself at http://localhost:5000, but there is also **Swagger UI** available at http://localhost:5000/apidocs. Documentation on the endpoints and how to interact with the radio is presented there.
 
 Once a radio stream is started, use any RTSP capable client (**VLC** is recommended) to connect to the stream at [rtsp://localhost:8554/radio/[radio]/stream](#). You'll need to replace `[radio]` with the name of the radio for which you have started the stream.
+
+For more detail on interacting with the microservice, see the system [state flow diagram](./docs/state.md) in the `/docs` folder.

docs/state.md

@@ -0,0 +1,129 @@
+# Microservice state flow
+The microservice doesn't operate on a strict state machine but the below diagram gives a rough indication of how to operate a radio from the REST interface.
+
+For brevity, state transitions caused by errors are omitted from the diagram - but there are a lot of possible reasons why the state could get bumped backwards to **Idle** or **Disconnected**.
+
+Each radio that is available on the system is configured indepdenently, with the exception that the endpoint `/radio/report` will interact with all radios. Dependending on the driver this might cause the radio to stop streaming or to disconnect entirely.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Disconnected
+    Disconnected --> Disconnected : report
+    Disconnected --> Connected : [radio]/connect
+
+    state Idle {
+        Connected --> Tuned : [radio]/configure/[]
+        Tuned --> Tuned : [radio]/configure/[]
+    }
+    %%Connected --> Connected : [radio]/info
+
+    Idle --> Disconnected : [radio]/disconnect
+    Idle --> Idle : [radio]/info
+
+    Tuned --> Streaming : [radio]/start
+    Streaming --> Tuned : [radio]/end
+    Streaming --> Streaming : [radio]/info
+```
+
+## Playing RTSP streams
+Thanks to the way the RTSP relay and/or the RTSP player you may be using, interruptions to the stream will cause players to disconnect. That means that annoyingly the procedure for re-tuning the radio are as follows:
+- End the stream (remote player(s) will disconnect)
+- Configure the radio to new frequency
+- Start the stream
+- Resume/reconnect playback on remote player.
+
+The gist of this is that you can't seamlessly transition from one radio station to the other without a stream interruption. It's not a limitation of the radio, I just can't be bothered making this demo significantly more complicated just to achieve that.
+
+## Getting state information
+The endpoint `/radio/<radio>/info` can give some indication of the operating state of the radio.
+If the radio is:
+- Disconnected state: returns **HTTP 400 Bad Request**
+- an Idle state: returns a JSON dictionary with the parameter `{'streaming': false}`
+- Streaming state: returns a JSON dictionary with the parameter `{'streaming': true}`
+
+```json
+{
+  "capabilities": {
+    "clock-sources": [],
+    "gpios": [],
+    "register-interfaces": [],
+    "rx": {
+      "antennas": [
+        "RX"
+      ],
+      "bandwidths": [],
+      "formats": [
+        "CS8",
+        "CS16",
+        "CF32"
+      ],
+      "frequencies": [
+        "RF",
+        "CORR"
+      ],
+      "gains": [
+        "TUNER"
+      ],
+      "sample-rates": [
+        250000,
+        1024000,
+        1536000,
+        1792000,
+        1920000,
+        2048000,
+        2160000,
+        2560000,
+        2880000,
+        3200000
+      ],
+      "sensors": []
+    },
+    "time-sources": [
+      "sw_ticks"
+    ],
+    "tx": {
+      "antennas": [
+        "RX"
+      ],
+      "bandwidths": [],
+      "formats": [
+        "CS8",
+        "CS16",
+        "CF32"
+      ],
+      "frequencies": [
+        "RF",
+        "CORR"
+      ],
+      "gains": [
+        "TUNER"
+      ],
+      "sample-rates": [
+        250000,
+        1024000,
+        1536000,
+        1792000,
+        1920000,
+        2048000,
+        2160000,
+        2560000,
+        2880000,
+        3200000
+      ],
+      "sensors": []
+    },
+    "uarts": []
+  },
+  "device": {
+    "driver": "rtlsdr",
+    "label": "Generic RTL2832U OEM :: 00000001",
+    "manufacturer": "Nooelec",
+    "product": "NESDR SMArt v5",
+    "serial": "00000001",
+    "tuner": "Rafael Micro R820T"
+  },
+  "name": "rtlsdr",
+  "stream-path": ":8554/radio/rtlsdr",
+  "streaming": false
+}
+```