Reverse API

Introduction

This feature has been added in version v4.3.2 to be able to forward channel and device settings changes to an external application using the same REST API interface as the one used to communicate settings changes to SDRangel. These AP endpoints are used:

• /sdrangel/deviceset/{deviceSetIndex}/device/settings with PATCH method to transmit device settings. The deviceSetIndex variable is the targeted device set index (unsigned integer)
• /sdrangel/deviceset/{deviceSetIndex}/channel/{channelIndex}/settings with PATCH method to transmit channel settings. The deviceSetIndex variable is the targeted device set index (unsigned integer) and the channelIndex variable is the channel sequence number (unsigned integer).
• /sdrangel/deviceset/{deviceSetIndex}/device/run with POST method to transmit start device action. The deviceSetIndex variable is the targeted device set index (unsigned integer)
• /sdrangel/deviceset/{deviceSetIndex}/device/run with DELETE method to transmit stop device action. The deviceSetIndex variable is the targeted device set index (unsigned integer)

Originator information

Note: this is implemented since v4.5.2

The JSON payload contains the following keys to identify which plugin instance has sent the message:

• originatorIndex: for device plugin instances this is the device set index that corresponds to the tab number in the GUI
• originatorDeviceSetIndex: this is also the device set index but for channel plugin instances
• originatorChannelIndex: this is the channel index of the channel plugin instance

Your targeted application can use this data to talk back to the right plugin (device or channel) instance in the SDRangel application.

Examples:

HackRF (in R0) change of frequency:

{
  "deviceHwType": "HackRF", 
  "hackRFInputSettings": {
    "centerFrequency": 434000000
  }, 
  "originatorIndex": 0, 
  "tx": 0
}

HackRF (in R0) start or stop:

{
    "deviceHwType": "HackRF", 
    "originatorIndex": 0, 
    "tx": 0
}

NFM demod (in R0 second position) change of delta frequency:

{
  "NFMDemodSettings": {
    "inputFrequencyOffset": 10000
  }, 
  "channelType": "NFMDemod", 
  "originatorChannelIndex": 1, 
  "originatorDeviceSetIndex": 0, 
  "tx": 0
}

GUI features

The forwarding of settings and/or start/stop action can be activated via GUI along with the connection parameters: address, port, device and if applicable channel indexes.

From device GUI

This is accessed by right clicking on the start/stop button as described here: https://github.com/f4exb/sdrangel/blob/master/sdrgui/readme.md#212-right-click

From channel GUI

This is accessed by clicking on the top left grey square as described here: https://github.com/f4exb/sdrangel/blob/master/sdrgui/readme.md#6-channels

Usage

Synchronizing another SDRangel instance

This feature can be used to forward changes directly to another SDRangel instance in order to synchronize it. However this works only if the targeted device or channel is of the same type. To mix types you need an application in the middle that will translate the JSON payload to adapt it to a different device or channel.

Communicate with any application

An application that implements the REST API interface being used will be able to interpret the JSON content and derive some actions from it. A very simple example that just echoes what it receives has been developed here: https://github.com/f4exb/sdrangel/blob/master/swagger/sdrangel/examples/reverseapi.py

This example uses Python flask package for the server and can serve as a starting point to elaborate more complex scripts to action hardware interfaces or forward the changes in any other form to any other application. The Python requests package can be used on client side as seen in the other scripts of the examples directory.