Programming OpenScope MZ from C++ under Windows

[JShort]

I am an experienced avid-hobbyist/semi-pro at both electronics and computer programming.  I program under Windows using MS Visual C++, and I have for many years worked with devices for analog data acquisition.  I have written some pretty sophisticated programs for doing so.

I recently discovered the OpenScope MZ and thought "open-source oscilloscope, sounds like fun," and so I bought one.  Being who I am, I want to write my own code to use this thing, and I want to be able to explore its possibilities.  I want to do that under Windows using C++.  I would like to do my own user interface and use the digital lines to detect positions of an external range switch, for instance.

WaveForms Live is OK if all I want to do is use the oscilloscope.  It doesn't do much with the digital lines.  That it requires a browser to run and that it is finicky about which browser is running it are strikes against it in my opinion, as well.

The documentation on the Digilent website is almost entirely aimed at the beginner.  The only more advanced thing I see is the Digilent Instrumentation Protocol.  It contains nothing about how to use the code it describes.  Presumably, that would be done under Arduino with the Digilent Core installed, but when I tried to install it, Arduino said an error occurred when downloading, so I can't use that.  I also have the latest version of Arduino; that an older version seems to be needed is not the way it should be; whoever is maintaining this needs to keep up.

I see from the Instrumentation Protocol that there are parameters like gain for which there is no documentation of values, ranges, etc.

Again, I want to work with the OpenScope MZ in the programming environment, Visual C++, with which I am experienced.  Where can I find documentation on how to do that.?  Is there not an API whereby I can call functions in the DLL's that interface the device?  What about serial communications?  The device shows up as COM4 in Windows Device Manager, so that means seems to be there.  How do I use it?

Where can I find documentation of how to access this device form C++, or any other language?  Where is the documentation on low-level programming, communications protocols, gain settings, etc., etc., etc.?  Since this thing is "open source," all such documentation should be readily available.  Where is it?

JShort

[JShort]

Quote

 

Pardon my rant.  I did some digging and found out on another post that you can send and receive the JSON code over the serial port at a baud rate of 1250000.  The posting did not say what the other parameters were, but I quickly found out that they are 8 bits with 1 stop bit and no parity.  I am able to do so from my C++ code easily.

However, the fact that I had to spend a lot of time digging in the Forum to find this out underscores my opinion that the documentation for this device could be better.  This is important information, and it should be easy to find.

There also needs to be more information about command parameters, what they mean, what values are valid, and so on.  For instance, there is nothing in the Instrumentation Protocol about how to specify the number of samples to be read by the oscilloscope read command.  The example for the read command shows a return of 1024 bytes, 512 16-bit words, but the examples for getCurrentState and setParameters show a buffer size of 32000, but there is no parameter for the number of samples to be read.  How did 1024 bytes / 512 samples get specified?

The acqCount parameter is also mysterious.  The documentation for the read command states that data will be returned if the "device acqCount" is greater than or equal to the "command acqCount," but the example shows a read command with an acqCount parameter of 101, which I assume is the "command acqCount," with the returned data having an acqCount (the "device acqCount?") of 3.  I am confused; what does acqCount do?  What is it used for and how is it used?

All of this leads to the question:  where are these details documented?  I suppose I can figure it out the hard way, but it would be nice to be able to have some kind of guide to all of this.

Lacking such documentation, if someone could answer the two questions posed above - number of samples and acqCount - I would be most grateful.

As one whose internet connection can be excruciatingly slow, I would also like to have downloadable documentation in a printer-friendly format like PDF.  Is there any such thing?

[JColvin]

Hi @JShort,

I have asked another engineer more familiar with the Instrumentation Protocol and JSON commands for their input.

Unfortunately, we do not have any nicely put together/single page documentation for the Instrumentation Protocol as far as I am aware.

Thank you,
JColvin

[JShort]

It is indeed unfortunate that documentation is lacking.  Even something that is not "nicely put together" or "single page" would be helpful.

I able to send JSON commands and receive the responses, but I am having big trouble with the "osc":"read" command.  I have a program that can output waveforms of various frequencies through the computer's audio system and have it making a 1000 Hz sine wave that is ±1 volt peak-to-peak; since I am new to OpenScope I don't want to rely on being able to make the AWG do its thing just yet.  The OpenScope MZ is connected to this, and I verified the connection by running WaveForms Live and seeing the expected 1000 Hz sine wave.

I set up the "osc" device with a buffer of 2048 samples at 100K samples/sec and a gain of 1.  The "trigger" was set to lower limit 0, upper limit 10 and no delay, and the "trigger":"single" command was issued  All of these returned statusCode 0.  All of this is on "osc" channel 1;

When I issue the "osc":"read" command the flashing blue LED on the device goes out and the leftmost red "user" LED comes on (something else that's not documented).  I get the "in use" statusCode from "osc":"read" until I issue "trigger":"forceTrigger" (the red LED goes out and the blue one starts flashing again).  What I get in the data looks like a signal of a steady DC voltage of just under 900 mv with some low-level white noise.  Then about half way into the buffer there is a high positive spike (level as yet undetermined) and then nothing but zeroes.

Can you or someone else tell me what is going on here?  This almost looks like nothing is connected to the input, and the long delay is because the trigger condition is not being met.  The spike and drop to zero don't make sense either.  And also, the response to the "osc":"read" has what appears to be a hexadecimal number at the very beginning, before the opening '{'; what is that?

The lack of documentation has set me on a voyage of discovery.  Some kind of map of charted territory would be most helpful.  I have downloaded the firmware source code and can find the keywords from the Instrumentation Protocol in the code, but the firmware seems to be mainly a JSON interpreter and is mostly about parsing and so on, making connecting keywords to actions difficult.  I will also download the WaveForms Live source code and study it as well.  Don't the programmers who created the firmware have notes, tables or whatever that they referred to when they did their thing?  Is there nothing available at all  for someone like me?  And what on earth is menu mode?

As I have said, I am an experienced programmer.  I am also a pretty good writer.  If I can learn all of this, I will write some kind of documentation and include code for a C++ API and some example applications, and I will share this with the OpenScope community.  Some topics like NIC and Wi-Fi are beyond my expertise, but if I get this started, I am sure that there are those in the community who will fill in the gaps.

Please help.  For the time being, I need an answer to why "osc":"read" is not returning what I expect.

Thank you.