Can we have more documentation on the API

[middelink]

First off, awesome work!

After reading the API header files (which seem to be the only documentation) I am left with questions like:

1. is the library thread safe?
2. can I open multiple request streams at the same time? the interface seems to imply it.
3. does the scope start sampling when I open the request,. or do I need to call request_has_data()?
4. it would be awesome to know which functions would actually block, aka waiting for samples. Same for functions which would allocate huge amounts of memory, aka the nScope_request_data with nrSamples. does it keep them in memory? What does the antialiased argument mean? number of actual samples it will combine into one aliased return sample? just a true/false?
5. what is nScope_request_data_stream() for? there does not seem to be a callback function I can register. I guess it is an unlimited sampler.
6. nScope_request_has_data seems to close the request when there is no more data? Does that mean if I call it to quickly (and there is no new sample available yet, it will... block? close the handle?
7. Library error codes are undocumented
8. why the huge amount of ways to set the sample rate? Don't they not all amount to nScope_set_sample_rate_in_hz(x * )? I mean... a double can be made real small ^^
9. Similar question for the pulse with settings etc.
10. Can we have defines for some limits? Like what are the lower and upper boundaries of the setGain, or should I do a binary search on the highest value the call accepts each time my app starts? (range for slider control)
11. what are the nScope_get_ch_level() about?
12. what use is nScope_get_num_channels_on() and nScope_get_channels_on() - i presume i need to give get_channels_on an array of ints the size of get_num_channels_on? Also it looks like the API is pretty much hardcoded for 4 channels, 2 analog and 2 pulsers. why suddenly these variable sized getters? also... setters and their counterpart getters should have the same signature. (esp the multi channel ones)

Just some thoughts ^^

[davidjmeyer]

API documentation is still on the TODO list. It's been such a rush to get this project to where it is now, we haven't had time to formally document. I can try to answer your questions quickly though.

1. The library is thread safe. We use this library to write the nScope program itself. 2-4: Generally, when you make a request for data, nScope immediately goes to record new data, and it starts streaming back up to the host computer, and gets stored in a queue (inside the request object). It keeps that data in it's own memory until you read it all, then it declares the request finished. read_data() blocks until there is a sample ready to read. wait_for_request_finish() waits until all the data from the request has been transferred to the host. Anti-aliasing argument is a true/false flag, and activates a sampling algorithm that prevents a scope trace from aliasing high-frequency signals. Generally should not be used when trying to obtain normally sampled data.

5: request_data_stream() is unimplemented right now, but will be used for obtaining continuous data, as opposed to a finite number of samples. Useful for roll mode in a scope environment.

6: request_has_data() will return true if you have not completed reading all data from the request. If you call it too quickly (before any data has reached the host) it will return true. A quick subsequent call of read_data() will block until data is available on the host.

7: yes they are. but you can generally see what they mean by sifting through the python or matlab implementations. They will be documented eventually.

8-9: I like convenience. Always love the feeling of a library that doesn't make me do conversions.

10: Generally, there are errors for parameters being too large or too little. -110 value error, parameter too small -111 value error, parameter too large -112 value error, parameter out of range However, not all of these have been implemented, and I cannot guarantee that nScope will not crash if you exceed limits that I haven't documented yet. I'm working on it...

11: ch_level() will allow users to change the range of voltage nScope is sampling. They are not implemented yet.

12: get_num_channels_on() returns how many channels are on, from 0-4. get_channels_on() is supposed to tell you which of the channels are on. I'm open to other designs.

Thanks again for your thoughts/questions. I hope it helps you get a bit further off the ground with working with the API.

[mushenghe]

Hi, is this nscope python API only works for python3? Can I use this in python2? I got error saying no module named nscopeapi when running in python2, I'm wondering what I can do to solve this error