Many bugs in API documentation

Add useful snippets of code or links to entire SDR projects.
Post Reply
User avatar
neok
Posts: 10
Joined: Mon Oct 17, 2016 8:11 am

Many bugs in API documentation

Post by neok » Sat Oct 22, 2016 5:31 am

Hi

I just bought two SDRPlay RSP1 units, one for me and one for a friend,
with the intention of developing our own software for Linux. We need
some functionality for specific uses of a wideband SDR receiver running
on the Linux OS.

The main reason for choosing SDRPlay was the availability of an API for
Linux _and_ _with_ an apparently detailed and useful API documentation.
Other competing devices, as far as I could tell by searching, did not
supply API documentation, nor were email enquiries on the subject replied.

I already have a working application which uses an RTL-SDR device via the
librtlsdr API, (itself sparsely documented) and I am now trying to add code
to the app to work with the RSP1. Unfortunately though, I very quickly run
into very buggy code when I tried to use the API documentation, especially
the example code in Section 4, API Usage. Some functions shown there have
the number of arguments that does not agree with the function's protoype,
as shown in the API doc (usually less). Some function prototypes, as shown
in the API doc, actually do not agree with the prototypes in the header
file <mirsdrapi-rsp.h> so it was necessary for me to pick up the protoypes
from the header file itself.

I eventually managed to get the example code to work but not before a lot
of time and effort was spent to identify and fix all these bugs. So, I am
now wondering if I will be able to eventually develop the code so that it
is incorporated in my application and whether I will get useful results.
I am also wondering how other developers fared with the API documentation
and how they managed to produce apps like SDRUno and others that are
available, for Linux and Windows. Is there a "proper" API documentation,
perhaps an "insider's version", that works properly? Have any other devs
came across this problem? I would like to know before I spend a lot of
time and effort on this effort!

My thanks in advance!
Last edited by neok on Thu Jan 01, 1970 12:00 am, edited 0 times in total.
Reason: No reason

sdrplay
Posts: 978
Joined: Wed Jan 07, 2015 7:58 am

Re: Many bugs in API documentation

Post by sdrplay » Sat Oct 22, 2016 7:52 am

The example in section 4 is really pseudo code and wasn't designed to be run (as it doesn't do anything) - it's intention was to show the order in which operations need to be done. If there are inconsistencies, please let us know and we'll update the document. In future versions of the document we'll make sure the example code can be compiled as is.

If you want to look at existing code, I would recommend:

https://github.com/SDRplay/examples
https://github.com/Analias/gr-osmosdr-fork-sdrplay
https://github.com/krippendorf/gr-osmosdr-fork-sdrplay
https://github.com/SDRplay/dump1090_sdrplus

If you have specific issues that you need help with, we are happy to look at any code that uses the API to help.

Best regards,

SDRplay Support

Reason: No reason

User avatar
neok
Posts: 10
Joined: Mon Oct 17, 2016 8:11 am

Re: Many bugs in API documentation

Post by neok » Sat Oct 22, 2016 8:02 am

Thank you!

I will keep a record of any significant bugs outside the example code and report.

Neoklis
Last edited by neok on Thu Jan 01, 1970 12:00 am, edited 0 times in total.
Reason: No reason

User avatar
neok
Posts: 10
Joined: Mon Oct 17, 2016 8:11 am

Re: Many bugs in API documentation

Post by neok » Sun Oct 23, 2016 4:06 am

Hi

I have made corrections to whatever discrepancies I came across in the API doc and
uploaded a text format copy to my website: http://www.5b4az.org/pages/Mirics-API.txt

I listed changes at the top of the document and as comments in the body of it. I get
the impression the the API doc is for an older version of the API, as there are differences
in some enumerated types and also references to depricated functions.

My 2euro's worth.... ;)

Neok
Last edited by neok on Thu Jan 01, 1970 12:00 am, edited 0 times in total.
Reason: No reason

sdrplay
Posts: 978
Joined: Wed Jan 07, 2015 7:58 am

Re: Many bugs in API documentation

Post by sdrplay » Sun Oct 23, 2016 7:12 am

The undefined states in the enums are new optional states for the Reinit which is a new function. They aren't strictly necessary but may be useful so I'll add them to the next release of the document.

SetTransferMode is really an undocumented feature. It was added to support Android initially but it can be used on other platforms. We haven't really fully tested it, so that's why it's not in the documentation. We may do in the next version if I can do some testing with it.

I couldn't see what your correction is to the StreamCallback?

Thanks for the feedback.

Best regards,

SDRplay Support

Reason: No reason

User avatar
neok
Posts: 10
Joined: Mon Oct 17, 2016 8:11 am

Re: Many bugs in API documentation

Post by neok » Sun Oct 23, 2016 8:45 am

The difference is that some arguments are shown as pointers. Below is
the arguments in the mirsdrapi-rsp.h :

short *xi,
short *xq,
unsigned int firstSampleNum,
int grChanged,
int rfChanged,
int fsChanged,
unsigned int numSamples,
unsigned int reset,
void *cbContext

Below the arguments in the API documentation. It was the good old
GCC that pointed this out by refusing to compile...

short *xi,
short *xq,
unsigned int *firstSampleNum,
int *grChanged,
int *rfChanged,
int *fsChanged,
unsigned int numSamples,
unsigned int reset,
void *cbContext

Neok

Reason: No reason

sdrplay
Posts: 978
Joined: Wed Jan 07, 2015 7:58 am

Re: Many bugs in API documentation

Post by sdrplay » Sun Oct 23, 2016 8:57 am

oh in 3.26 - I was looking at 3.3 that's why I couldn't see it.

Thanks, will update the document.

Best regards,

SDRplay Support

Reason: No reason

Post Reply