Documentation for return values in API

[nocarryr]

In an effort to build tests for error codes as returned by librtlsdr within the pyrtlsdr wrapper in this PR, I've found some of the functions in the header with either undocumented or possibly mis-documented return values.

• rtlsdr_open and rtlsdr_close do not indicate a return value for errors. We all know from experience that -1 is returned on error with rtlsdr_open, but since I have never encountered an error on close, I am unsure.
• rtlsdr_set_center_freq indicates a return of 0 on error, but in working with a connected dongle, it appears to be returning 0 for success instead.
• rtlsdr_get_freq_correction does not indicate a return value for an error. This would likely be the intended functionality since the values can be positive and negative integers as well as 0
• rtlsdr_get_tuner_gain indicates a return of 0 on error, but it would seem that 0 is a valid gain value. I raised this as an issue in the original project here but it was never resolved.
• rtlsdr_reset_buffer does not indicate a return value for errors
• rtlsdr_read_sync does not indicate a return value for errors

Any direction or clarification that can be given for any of those would be greatly appreciated. Thanks!

[racerxdl]

Hi @nocarryr , about the methods:

In rtlsdr_open it can return 0 for success, but can also return -1 in case of rtlsdr error, or any of the libusb errors for example LIBUSB_ERROR_ACCESS in case of an error of libusb (like permissions or so). rtlsdr_close will only return 0 or -1.

For rtlsdr_set_center_freq will return the frequency that has been set in success or -1 in error. Just check if the library you're using is the same version of ours (the upstream in distros are very far away from this repository).

rtlsdr_get_freq_correction will return 0 in case of error, but as noticed by you, it can also return 0 because the correction is 0. This is just a memory value in the library, it doesn't actually read the device, so there is no error involved.

rtlsdr_get_tuner_gain 0 is actually a valid gain value for some tuners. This doesn't actually query the device for available gains (most of the Tuners doesn't have that feature). Instead it loads a lookup table hardcoded to the C Library. It will return -1 in case of no connected device, 0 if no gains are available for the tuner (for example FC2580) or the number of gains.

rtlsdr_reset_buffer returns -1 in case of no connected device. 0 otherwise.

rtlsdr_read_sync returns -1 in case of no connected device, libusb error, or the number of bytes read.

So for the possible LIBUSB errors you can check here: http://libusb.sourceforge.net/api-1.0/group__misc.html

Most of the calls will either return -1 or a libusb error.

Hope that can help you

[nocarryr]

Thanks @racerxdl for the info. I am not quite as familiar with the lower-level and device-level stuff as I should be.
I almost had a face-palm moment when I remembered I had recently installed gnu-radio through my package manager (which depends on Ubuntu's release of librtlsdr). After uninstalling and ensuring I was linking to the build off of the master branch of this repo, I still got a return value of 0 for rtlsdr_set_center_freq:

    115        result = librtlsdr.rtlsdr_set_center_freq(self.dev_p, freq)
    116        if result <= 0:
    117             self.close()
    118             raise IOError('Error code %d when setting center freq. to %d Hz'\
--> 119                           % (result, freq))
    120 
    121         return

OSError: Error code 0 when setting center freq. to 80000000 Hz

So in order to not break things in pyrtlsdr, I'll have to continue to assume that result < 0 is an error.

In light of all of this, I do see value in updating the comments in the header to make things less confusing for those wrapping the library.

I could start a PR, but I am unsure of how well that would work out given my lack of experience in C and the related libusb. What are your thoughts?

[racerxdl]

I will try to rewrite the doc sometime, if you want you can start a PR and then I can add the stuff that is missing.

The rtlsdr_set_center_freq should return the frequency that has been set. That's weird. In our C# Wrapper its working fine.

[nocarryr]

After digging around in the source, it seems that the functions related to rtlsdr_set_center_freq are returning, or at least internally checking for a value < 0, but I don't see how the frequency value gets assigned to the return variable:

• https://github.com/librtlsdr/librtlsdr/blob/master/src/librtlsdr.c#L987-L1013
• https://github.com/librtlsdr/librtlsdr/blob/master/src/tuner_r82xx.c#L1274-L1304

Is it from the call to rtlsdr_i2c_write_fn that is called by r82xx_write_reg_mask?

I don't want to turn this into a course in C, so there's no need to go into detail if it's not a quick answer. (Just always willing to learn things)

Also rtlsdr_read_sync is returning the result from libusb_bulk_transfer which returns 0 on success. The pointer n_read is what receives the value for number of bytes read. (Again, feel free to correct me here)

Regarding rtlsdr_get_tuner_gain, I think you may have been describing rtlsdr_get_tuner_gains in your response. This might actually be better suited for another discussion so I'll try and keep it short.

When retrieving the tuner's current gain value, assume that its gain is set to 0db. Since 0 is the value indicating an error, how can we know whether we encountered an error or not? This one is more about altering the behavior than clarifying the documentation so we can save it for another time.

I'll take a stab at the rewrite and see how far I can get. Thanks again

[racerxdl]

Just checked, its using the return from dev->tuner->set_freq(dev, freq - dev->offs_freq);, so maybe the tuner you're using has a code that does not return the frequency as expected. I always test with a R820T2 (that is the most common nowadays). Can you confirm your tuner? If its different, I will take a look and open a ticket if the behaviour is wrong.

[nocarryr]

I have an R820T. When initialized, stdout displays:

Found Rafael Micro R820T tuner

And rtlsdr_get_device_name gives me 'Generic RTL2832U OEM'

Could there really be that much difference between the R820T and the R820T2?

Edit:
Now that I'm looking at the performance differences between the two, I think I might be ditching this piece soon, lol

[hayguen]

R820T and R820T2 tuner are identical in the source.
There's even no way to discriminate both tuners.

[racerxdl]

Yeah, like @hayguen said, the R820T/2 differences are only hardware based. No software changes. So its weird. I will make some tests again just to make sure there is no bug there.

[hayguen]

• now fixed/amended API documentation for the requested functions:
  you were right: rtlsdr_set_center_freq() does NOT return the frequency
• replaced all 'R820T' by 'R820T/2',
  to indicate that both tuner models cannot be distinguished

[nocarryr]

@hayguen found those changes in 756d05c and dc1e5a1

Thank you!

Any idea when they'll be merged to master?

[hayguen]

@nocarryr
the latest changes on master are from Feb 2017 ..
and there are many many changes and enhancements on the development branch.
just yesterday i opened #76 , that i'd like to make a new release.
currently, i'm having a look at several issues .. but i'd like to be finished within 1 1/2 weeks.

would be good, if you (and others) have a look at the development branch!