Hantek has an SDK manual for the Display DLL, and one for the acquisition DLL (HTMarch). I concentrated on the later.
There are a set of support functions, which mostly make sense. Other than the fact that some of them are worthless (redundant), since the data they set gets overridden whenever you actually do a Read call. Here's my summary, and notes:
--Documented HTMARCH acquisition support functions [Mark_O, Oct'13]:
// just checks to see if a device is present. usually only Dev=0 is true.
HTMARCH_API short WIN_API dsoOpenDevice(unsigned short DeviceIndex);
// cals are 32B of 'proofreading' data. short the inputs to Ground, then run dsoCalibrate and retrieve data.
// presumably, the cal sets (16B/channel) are dependent on timePerDiv and voltsPerDiv, which means that
// dsoCalibrate would need to be run in multiple passes (64 combos). it also suggests that dsoSetCalLevel
// must be run every time either is changed. what dsoGetCalLevel is good for is unknown.
// cal data also needs to be reloaded on every power-on, since theres no NVMEM. [not really. it says it
// sends the Cal data to the device, but it doesn't. The SDK uses it to adjust the data before returning it.]
// [it looks like dsoSetCalLevel/dsoGetCalLevel are also worthless, for the same reasons as SetTime/Volts (below).]
HTMARCH_API short WIN_API dsoCalibrate(unsigned short nDeviceIndex,int nTimeDIV,int nCH1VoltDIV,int nCH2VoltDIV,short* pCalLevel);
HTMARCH_API unsigned short dsoSetCalLevel(unsigned short DeviceIndex,short* level,short nLen);
HTMARCH_API unsigned short WIN_API dsoGetCalLevel(unsigned short DeviceIndex,short* level,short nLen);
// worthless functions, because there's no way to get any data after setting them, w/o running a dsoReadHardData, which overrides them!
// however, they do serve to document the needed index values. (perhaps there are undocumented Read functions that were dropped.)
HTMARCH_API short WIN_API dsoSetVoltDIV(unsigned short DeviceIndex,int nCH,int nVoltDIV);
HTMARCH_API short WIN_API dsoSetTimeDIV(unsigned short DeviceIndex,int nTimeDIV);
// nVoltDIV (0-7): n20mV, n50mV; n100mV, n200mV, n500mV; n1V, n2V, n5V
// nTimeDIV (0-27): n48Msa(0-10); n16MSa, n8MSa, n4MSa, n1MSa(14-24), n500KSa, n200Ksa, n100KSa
What is interesting there is the CalLevels, since they claim you send the data to the device, but I suspect you do NOT. I doubt any correction is ever applied in the module, but rather in the SDK interface routine, which applies a cal correction after a Read and before it passes the data back. I wonder how significant the args are for selecting channel sensitivity and sample rates, because in the worst case there are 8 sensitivities for each of Chan 1 and 2, and 8 sample rates, for a total of 512 combinations! They appear to combine the CalLevels for both channels into one block, of 32B.
The actual data reading is more interesting, since it appears to wrap up everything into one call. I guess you need to spawn this in a thread, so you can kill it later if the trigger condition never occurs, since there's no defined timeout. And you'd hang, otherwise.
--ONE call to Config AND Acquire, AND Retrieve (and Correct) sample data. [Mark_O, Oct'13]
--returns 0 for failure and non-0 for success.
HTMARCH_API short WIN_API dsoReadHardData(
unsigned short DeviceIndex, // access more than one module
short* pCH1Data, // ptrs to 2 storage buffers
short* pCH2Data,
unsigned long nReadLen, // length of 'reading data'
short* pCalLevel, // ** ptr to calibrationLevel vector (see dsoSetCalLevel); input?
int nCH1VoltDIV, // sensitivity settings (0-7=20mV-5V)
int nCH2VoltDIV,
short nTrigSweep, // sweepMode: 0=Auto, 1=Normal ??, 2=single
short nTrigSrc, // 0=chan1, 1=chan2
short nTrigLevel, // level=0-255
short nSlope, // 0=rise, 1=fall
int nTimeDIV, // sampleRate (0-27=48MSa-100KSa/s, see dsoSetTime)
short nHTrigPos, // pre-TriggerData: 0-100% (control pre/post buffering)
unsigned long nDisLen, // ** length of DisplayData (huh?)
unsigned long * nTrigPoint, // index of returned triggerPoint
short nInsertMode // ** D-value Mode: 0=Step, 1=Line, 2=SinX/X (huh?)
);
There are a number of not well-defined things here, but two that stand out as puzzling. The biggest is what a DisplayLength and D-value Mode are doing in the acquisition routine? They're both relating to Display, which is (and should be) separate. And the second is what the purpose of having a SweepMode of Normal is for?
Auto means just trigger immediately (ignoring the sh!tload of trigger parameters), and Single waits for one trigger hit to capture and return a sample set. But Normal implies there is a continuous sampling process occurring. And since there's no callback function or any other mechanism to allow that, I wonder if it's just that Normal=Single here, or if they partition the one block of data that's allocated into slices, and fill it with multiple samples in Normal mode? (I'd guess not, since that's far too sophisticated for them. So Single probably means nothing at all.)
I'd be interested in thoughts anyone may have as to the purpose of the Display params in the dsoRead, though.