sdrplay-fm-radio/docs/state.md

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.

stateDiagram
    Disconnected --> Disconnected : report
    Disconnected --> Connected : [radio]/connect

    state Idle {
        Connected --> Connected : [radio]/info
        Connected --> Tuned : [radio]/configure/[]
        Tuned --> Tuned : [radio]/configure/[]
        Tuned --> Tuned : [radio]/info
    }

    Idle --> Disconnected : [radio]/disconnect


    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}

{
  "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
}