Dongle programming interface

I’ve been receiving a number of questions about the programming interface for the FCD.

Although the quadrature I/Q stream is over a standard USB stereo soundcard interface, in order to change the centre frequency there is an additional programming interface that uses the USB HID standard interface. Here’s an example to set the centre frequency of the dongle give the frequency in kHz:

static unsigned char HIDSetFreq(HANDLE hWrite,HANDLE hRead,int nFreq)
{
 DWORD dwBytesWritten=0;
 DWORD dwBytesRead=0;
 unsigned char au8BufOut[65]; // endpoint size + 1
 unsigned char au8BufIn[65]; // endpoint size + 1

 au8BufOut[0]=0; // First byte is report ID. Ignored by HID Class
   // firmware as only config'd for one report
 au8BufOut[1]=100; // Command to Set Frequency on dongle
 au8BufOut[2]=(unsigned char)nFreq;
 au8BufOut[3]=(unsigned char)(nFreq>>8);
 au8BufOut[4]=(unsigned char)(nFreq>>16);
 WriteFile(hWrite,au8BufOut,65,&dwBytesWritten,0);
 ReadFile(hRead,au8BufIn,65,&dwBytesRead,0);
 return au8BufIn[2]; // au8BufIn[2]==1 if success.
}

The HID command output to the dongle is 64 bytes, as is the HID response input back into the host. You also need to prepend the buffers with one byte each for the HID report ID that’s not actually used, so 65 bytes total each.

In the output command buffer, after the unused HID report byte, the FCD command byte follows. The “SetFreq” command is 100. Following this is the 24 bit little endian integer frequency specified in kHz.

In response, the 65 bytes buffer includes a copy of the command (100 in this case) at index 1 and a boolean success/fail 1/0 response at index 2.

So far so good. But you need to open up input and output HID handles first to use this function! This is rather more fiddly, certainly in the Windows world. I have some example code here that demonstrates this: http://www.g6lvb.com/Fungle/FCHid002.zip

Howard

This entry was posted in Uncategorized. Bookmark the permalink.

17 Responses to Dongle programming interface

  1. Mike says:

    Looks great.
    For Mac OSX there is PyHID, which is a C++ library and also a Python class for the HID manager.

  2. Ken Nelson says:

    Will the funcube work the HF band also. .

  3. Dennis says:

    I’m having trouble finding how to set the FCD centre frequency.
    It states in the Spectravue Configuration Guide:
    “It is suggested that the program FCHid be running.
    Enter a frequency of 100MHz and click on the “Defaults” button.
    FCHid content should appear as shown below. (FCD F/W 18c)”
    I have no idea what this means or where to find this program. Surely it should be a simple task to enter this frequency.
    Any suggestions?
    Kind regards,
    Den

    • admin says:

      Hello Den.

      Assuing that you have the FCHid program up and running, all you need to do is enter the frequency in kHz and press the Set Frequency button. So, for 100MHz you’d enter 100000 and press the Set Frequency button. That’s all there is to it.

      The Defaults button is used to set some gain and filter settings if you are on the early 18b firmware. It does not set the frequency. Later firmware versions (including 18c) have the appropriate default settings set so there should be no need to use the Defaults button unless you want to go back to some sensible values after soe tinkering.

      Howard

  4. Rob says:

    Firmware and FCHid can be found here Dennis.
    http://www.funcubedongle.com/?page_id=313
    Rob

  5. Peter Stuge says:

    Would suggest using the open source library HIDAPI from Signal 11 to access the HID interface. For a later product version I’d suggest using a vendor specific interface to replace the HID one, and using libusb to access it.

    http://libusb.org/wiki/FAQ#CanIcreateadriverlessdeviceusingHIDclass

    • admin says:

      Peter

      That is what the QTHid stream of multiplatform code uses. HIDAPI is not without its limitations and “features” though.

      Howard

  6. Roger says:

    Please give me a hint how this call will be if I want to set the frequency to
    119000 KHz? WriteFile(hWrite,au8BufOut,65,&dwBytesWritten,0)
    I have manged to connect to funcube dongle through visual basic code but cant figure out this command. Its the au8BufOut I have problem with.
    /SA0AND

    • admin says:

      Hello Roger

      Have you had a look at this?

      static unsigned char HIDSetFreq(HANDLE hWrite,HANDLE hRead,unsigned int uFreq)
      {
      DWORD dwBytesWritten=0;
      DWORD dwBytesRead=0;
      unsigned char au8BufOut[65]; // endpoint size + 1
      unsigned char au8BufIn[65]; // endpoint size + 1

      uFreq*=1000U;

      au8BufOut[0]=0; // First byte is report ID. Ignored by HID Class firmware as only config'd for one report
      au8BufOut[1]=101;
      au8BufOut[2]=(unsigned char)uFreq;
      au8BufOut[3]=(unsigned char)(uFreq>>8);
      au8BufOut[4]=(unsigned char)(uFreq>>16);
      au8BufOut[5]=(unsigned char)(uFreq>>24);
      WriteFile(hWrite,au8BufOut,65,&dwBytesWritten,0);
      ReadFile(hRead,au8BufIn,65,&dwBytesRead,0);
      return au8BufIn[2];
      }

      Many thanks, Howard

  7. Roger says:

    Howard!
    Have I got it right that the au8BufOut should look like this for freq 119000?
    0
    101
    192
    203
    23
    7
    In my application it changes the freq in spectravue to 119000 kHz.

    But I am wondering what the response from FCD means? It returns
    0
    101
    1 !!!
    192
    203
    23
    7

    Is it described anywhere which other functions available for communication with FCD?
    /Roger SA0AND

    • admin says:

      Hello Roger

      There is no formally written spec, but I believe that all the publicly FCD HID APIs are demonstrated in the application.

      Many thanks, Howard

      • admin says:

        Hello Roger

        I think the “21” should be “23” if my hex conversion is correct. (119,000,000 is 0x07 17 CB C0)

        Howard

    • admin says:

      Roger,

      The “1” in the response indicates success.

      Many thanks, Howard