Web service API

[f4exb]

Implement a Web service style API to drive and/or request an SDRangel instance.

As a prerequisite the Model-View pattern should be enforced which is not the case today and can be the subject of another ticket. Both are prerequisites to proper macro feature implementation and possibly the creation of a headless version (server)

This API will be REST"ish" style if not fully RESTful compatible. It will use HTTP protocol over a configurable port and use JSON as the data interface. It will try to match as best as possible the HTTP methods usage described here: https://en.wikipedia.org/wiki/Representational_state_transfer

[f4exb]

The URL could be constructed like this for the plugins structure:

/device/{id | query}/channel/{id | query}

• "device" refers to the "sampling device" which in the UI translates into a set of related tabs (R0, R1, T2, ...)
• "channel" refers to the channel plugins attached to a "sampling device" which in the UI translates in the channel plugins visible in the "channels" window
• "id" is a key that uniquely identifies an object of the kind specified just before
• "query" is a query action on objects of the kind specified just before, For example:
  • "findBy...": find details of an object by its id, sequence, whatever
  • "count": to return the number of objects
  • "list": to list the details of all objects

Then the HTTP methods mapping is rather obvious:

• GET: get details
• POST: create a new object
• PUT: change the details of an object
• PATCH: modify the internal state of the program with an object like load a preset (less obvious this one)
• DELETE: delete an object

Details are specified in the JSON payload

[f4exb]

Sooner or later the user authentication will have to be addressed and the permissions attached to it. This will become more critical for headless operation of distant instances managing transponders or repeaters. In particular one may want to restrict the frequencies that may be tuned via the web interface.

[texasyojimbo]

Hi Eduoard,

I think this is definitely a cool idea.

One use-case for an API that I can foresee might be to trigger relays / coax switches to switch antennas, enable amplifiers, etc. This might require the web service host/server process to have pretty low latency to be effective though.

For example, an external program might run a simple loop that sends a request every 20 ms asking whether T1 is transmitting, and if so, triggers a transmit/receive switch and keys up a QRP amplifier. We obviously don't want too much lag in getting a response (more than a few hundred ms would be noticeable).

Of course -- to a large extent performance of such a system will depend on the competence of the third-party script writer (presumably the user/integrator) and no way you can control that. =D

(and of course ideally the hardware user -- I'm using LimeSDR -- would pull hardware state directly from hardware or hardware API -- but I'm not terribly clever -- I can write a Python script that queries a REST API, but Lime API is probably beyond my level of competence). =(

[f4exb]

What you suggest is rather messy (as polling is generally). What is acceptable is that the 3rd party software controls both SDRangel via API and the relays or whatsoever. Or if trigger comes from SDRangel this should be done via macro (see issue #49)

It is in the plans to support the GPIO board via the LimeSDR plugin.

[texasyojimbo]

Thanks Eduoard, I've looked into some other solutions like the one you suggest and think it is definitely more workable. Good work. =D

[f4exb]

Server with minimal interface working in v3.8.4 Uses swagger for API design see: https://github.com/f4exb/sdrangel/tree/master/swagger/sdrangel

[gvanem]

I'll comment on swagger.dll here instead of opening another PR.

From a pedump swagger.dll, I can see that the official MinGW-built swagger.dll exports everything! This seems to be the autoexport feature of GNU's ld in action. When trying to build swagger.dll using MSVC/clang-cl, it exports nothing!

In swagger/CMakeLists.txt it's supposed to generate an .DLL. But unless I try to built it as a static swagger.lib, there must be some decorations like class SWAGGER_API SWGDeviceSettings: ... for it to export classes and members for MSVCC/clang-cl.

But most of the swagger-code is generated. So I'm anxious to patch it.

[f4exb]

Technically I "own" the code generator that I have already customized. It is a matter of updating swagger-codegen/modules/swagger-codegen/src/main/resources/qt5cpp/model-header.mustache template. But then I also need to include the "util/export.h" file. This would be better if this is "export.h" instead which means changing this all over the place in the rest of the code.

[f4exb]

Released in v4.0.0