# 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
}
```