® MULTISPECTRAL SOLUTIONS, INC. ® RaDeKL Radar API for Windows Radar Developer’s Kit – Lite – Application Programming Interface Programmer's Guide Version 2.0 Revised: 05 OCT 07 © 2006 Multispectral Solutions, Inc. 20300 Century Boulevard Germantown, MD 20874-1132 Phone: (301) 528-1745 Fax: (301) 528-1749 Website: www.multispectral.
NOTE: The RaDeKL radar unit has been tested to comply with FCC Part 15, Subpart C for WBT devices. Changes or modifications to the radiating elements of RaDeKL not expressly approved by the party responsible for compliance could void the user’s authority to operate the equipment. NOTE: The RaDeKL radar unit has been tested and found to comply with the limits for a Class B digital device, pursuant to part 15 of the FCC Rules.
RaDeKL Radar API Programmer’s Guide I Table of Contents Part I: Welcome to the RaDeKL Radar API....................................................................1 Introduction.................................................................................................................................... 1 USB Driver Installation.................................................................................................................. 1 Programming Notes ........................................
RaDeKL Radar API Programmer’s Guide II Part VI: Radar Register Functions ...............................................................................32 RaDeKL_WriteCheckRegister .................................................................................................... 32 RaDeKL_WriteRegister ............................................................................................................... 33 RaDeKL_ReadRegister......................................................................
RaDeKL Radar API Programmer’s Guide 1 Part I: Welcome to the RaDeKL Radar API Introduction The RaDeKL Radar API provides a programming interface to the Multispectral Solution Inc. (MSSI) RaDeKL Radar device. Using this interface removes the burden of designing code to access the USB interface and dealing with the specifics of radar commands and operational parameter settings.
RaDeKL Radar API Programmer’s Guide 2 7. Windows 2000: a. Click “Search for a suitable driver for my device”. Click “Next”. b. Check the box “Specify a location”. Click “Next”. c. Click “Browse” and navigate to the folder noted in step 2 and then down to the “Driver” folder. Select the file named “FTDIBUS.inf” and click “OK” and then “Next”. d. The driver will install. Windows will then detect a second USB device and the driver will install automatically. 8.
RaDeKL Radar API Programmer’s Guide 3 Programming Notes In order to use the RaDeKL Radar API, please follow these steps (illustrated using Visual C++ 6.0): 1. Copy FTD2XX.h, RaDeKLAPI.h and RaDeKLAPI.lib (from subfolder “Library” in the folder noted in step 2 above, “USB Driver Installation “) into the folder that contains the development environment of your project. Ensure that the files are copied (not moved) otherwise you won’t find them for the next project. 2. Include RaDeKLAPI.
RaDeKL Radar API Programmer’s Guide 4 Usage Warnings For proper operation of the RaDeKL radar unit using this API, please consider these warnings: 1. When operating the RaDeKL Radar in continuous detection mode, range data is continuously streamed from the radar unit to the PC. While in this mode, the only operation, other than reading this data, should be to stop continuous mode (using RaDeKL_StopContinuousDetection or a lowlevel register write to do the same).
RaDeKL Radar API Programmer’s Guide 5 Part II: Status Formatting Functions RaDeKL_GetStatusText Get the text associated with a status code. Most functions in this API return a numeric status code. RaDeKL_OK (0) indicates successful completion. Other codes (see below) indicate error conditions. Format: char *RaDeKL_GetStatusText (ULONG ftStatus); Parameters: ftStatus Numeric status code as returned by most RaDeKL API functions.
RaDeKL Radar API Programmer’s Guide 6 Example: Make a RaDeKL API function call to list available devices and display an error message if the call failed. ULONG DWORD char status; numdevs; **snum = 0, **desc = 0; status = RaDeKL_ListRadars (&numdevs, &snum, &desc); if (status != RaDeKL_OK) { printf (“Unable to list devices: %s\n”, RaDeKL_GetStatusText (status)); return status; } // All OK return RaDeKL_OK; © Multispectral Solutions, Inc.
RaDeKL Radar API Programmer’s Guide 7 RaDeKL_GetAPIVersion Retrieve the version number of this API. The major version number is in the high-order word and the minor version number is in the low-order word. See example for details of usage. NOTE: The Version information returned by this function is the version of this API, not the version of any radar unit attached. To obtain radar unit version information, use function RaDeKL_GetDeviceInfo after the radar has been opened.
RaDeKL Radar API Programmer’s Guide 8 Part III: Radar Management Functions RaDeKL_ListRadars Get a list of all RaDeKL Radar devices connected to the system. Note: This function will only retrieve RaDeKL Radar devices and will ignore other devices that may be based on the same FTDI USB Chip. Each device has a serial number (up to 15 chars) and a device description (up to 63 chars). The serial number can then be used in a call to RaDeKL_OpenRadar to open the device.
RaDeKL Radar API Programmer’s Guide 9 Example 1: List all available radar units and display the information obtained. ULONG status, i; DWORD numdevs; static char **snum = NULL, **desc = NULL; // or make these global status = RaDeKL_ListRadars (&numdevs, &snum, &desc); if (status != RaDeKL_OK) { printf (“Unable to list devices: %s\n”, RaDeKL_GetStatusText (status)); return; } printf (“Number of devices detected: %d\n”, numdevs); for (i = 0; i < numdevs; i++) printf (“Device %d, Serial: %s, Description: %
RaDeKL Radar API Programmer’s Guide 10 RaDeKL_ListRadarsCleanup De-allocates the memory that was allocated in a previous call to RaDeKL_ListRadars. Normally, this is not required as each successive call to RaDeKL_ListRadars de-allocates these lists and Windows will do the final de-allocation when the program terminates. However, if the design calls for an explicit de-allocation, this function can be used.
RaDeKL Radar API Programmer’s Guide 11 RaDeKL_OpenRadar Open a RaDeKL Radar device as identified by its serial number. Serial numbers are unique for each specific unit. A list of all available RaDeKL Radar devices and their serial numbers is obtained by calling RaDeKL_ListRadars. Format: ULONG RaDeKL_OpenRadar (RaDeKL_HANDLE *handle_ptr, char *serial_number); Parameters: handle_ptr Pointer to a RaDeKL_HANDLE to receive the handle for the opened device.
RaDeKL Radar API Programmer’s Guide 12 RaDeKL_CloseRadar Close a RaDeKL Radar device previously opened by a call to RaDeKL_OpenRadar. Format: ULONG RaDeKL_CloseRadar (RaDeKL_HANDLE handle); Parameters: handle RaDeKL_HANDLE as returned by a call to RaDeKL_OpenRadar. Return Value: RADEKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes.
RaDeKL Radar API Programmer’s Guide 13 RaDeKL_GetDeviceInfo Get the device-specific information of a RaDeKL Radar associated with the handle. Format: ULONG RaDeKL_GetDeviceInfo (RaDeKL_HANDLE handle, RaDeKL_DEVICEINFO *info); Parameters: handle RaDeKL_HANDLE as returned by a call to RaDeKL_OpenRadar. info Pointer to a RaDeKL_DEVICEINFO structure. See the appendix for field definitions of this structure. Return Value: RADEKL_OK (0) if successful, a non-zero status otherwise.
RaDeKL Radar API Programmer’s Guide 14 RaDeKL_ResetRadar Perform a reset on the radar, resetting the device to factory settings and purging the send and receive buffers. NOTE: Resetting the radar causes all radar registers to be reset to factory default values. That means that the settings for DAC thresholds, TX and RX attenuation, range delay and detection intervals may no longer be the same as what the application thinks they are.
RaDeKL Radar API Programmer’s Guide 15 RaDeKL_FlushIO Flushes (purges) the transmit and receive buffers on the USB port the radar is connected to. Note that this does not necessarily flush the data on the FPGA radar processor chip ports. This function is intended only to flush the data waiting on the USB chip ports. To properly reset the RaDeKL radar device, use RaDeKL_ResetRadar instead.
RaDeKL Radar API Programmer’s Guide 16 Part IV: Radar Parameter Functions RaDeKL_SetThresholds Set the DAC Threshold values in the radar device. NOTE: There are currently 32 DAC Threshold registers with permissible values in the range from 20 to 227, but the actual number of registers and permissible values should be obtained by calling RaDeKL_GetDeviceInfo and using thresholds, threshold_min and threshold_max, as these might change with future versions of the radar unit.
RaDeKL Radar API Programmer’s Guide 17 RaDeKL_GetThresholds Get the DAC Threshold values from the radar device. NOTE: There are currently 32 DAC Threshold registers with permissible values in the range from 20 to 227, but the actual number of registers and permissible values should be obtained by calling RaDeKL_GetDeviceInfo and using thresholds, threshold_min and threshold_max, as these might change with future versions of the radar unit.
RaDeKL Radar API Programmer’s Guide 18 RaDeKL_SetTransmitAttenuation Set the TRANSMIT POWER ATTENUATION register in the radar device. NOTE: Transmit attenuation settings can currently be in the range from 0 to 63, but the actual range of permissible settings should be obtained by calling RaDeKL_GetDeviceInfo and using tx_atten_min and tx_atten_max, as these might change with future versions of the radar unit.
RaDeKL Radar API Programmer’s Guide 19 RaDeKL_GetTransmitAttenuation Get the TRANSMIT POWER ATTENUATION register value from the radar device. NOTE: Transmit attenuation settings can currently be in the range from 0 to 63, but the actual range of permissible settings should be obtained by calling RaDeKL_GetDeviceInfo and using tx_atten_min and tx_atten_max, as these might change with future versions of the radar unit.
RaDeKL Radar API Programmer’s Guide 20 RaDeKL_SetReceiveAttenuation Set the RECEIVE ATTENUATION register in the radar device. NOTE: Receive attenuation settings can currently be in the range from 0 to 255, but the actual range of permissible settings should be obtained by calling RaDeKL_GetDeviceInfo and using rx_atten_min and rx_atten_max, as these might change with future versions of the radar unit.
RaDeKL Radar API Programmer’s Guide 21 RaDeKL_GetReceiveAttenuation Get the RECEIVE ATTENUATION register value from the radar device. NOTE: Receive attenuation settings can currently be in the range from 0 to 255, but the actual range of permissible settings should be obtained by calling RaDeKL_GetDeviceInfo and using rx_atten_min and rx_atten_max, as these might change with future versions of the radar unit.
RaDeKL Radar API Programmer’s Guide 22 RaDeKL_SetRangeDelay Set the RANGE and DELAY registers in the radar device. These two registers shift the return data by a certain number of range bins. To simplify implementations, this function accepts a RangeDelay in feet and converts it to the required register values. The default value is 0 feet.
RaDeKL Radar API Programmer’s Guide 23 RaDeKL_GetRangeDelay Get the RangeDelay from the radar device by reading the RANGE and DELAY registers and converting the values to feet. Format: ULONG RaDeKL_GetRangeDelay (RaDeKL_HANDLE handle, DWORD *delay_feet); Parameters: handle RaDeKL_HANDLE as returned by a call to RaDeKL_OpenRadar. delay_feet Pointer to a DWORD to receive the delay value in feet. Return Value: RADEKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes.
RaDeKL Radar API Programmer’s Guide 24 RaDeKL_SetInterval Set the automatic detection interval for continuous detection mode. When the radar is in continuous mode, a new detection is performed each time this interval expires. The default setting is INTERVAL_50_MS.
RaDeKL Radar API Programmer’s Guide 25 RaDeKL_GetInterval Get the automatic detection interval for continuous detection mode in milliseconds. NOTE: There are currently 5 distinct interval settings (see table below), but the actual range of permissible settings should be obtained by calling RaDeKL_GetDeviceInfo and using interval_min and interval_max, as these might change with future versions of the radar unit.
RaDeKL Radar API Programmer’s Guide 26 RaDeKL_SimulatorMode The RaDeKL Radar API provides a transparent radar simulation mode. This allows programs using this API to be tested without the need to have an actual RaDeKL Radar unit present. By default, Simulator Mode is disabled, causing communications to occur with an actual radar device.
RaDeKL Radar API Programmer’s Guide 27 Part V: Radar Detection Functions RaDeKL_DetectSingle Perform a single radar detection and return the range bin data. NOTE: The number of range bins is currently 256 with possible data values between 0 and 32, but the actual number of range bins and the range of their possible values should be obtained by calling RaDeKL_GetDeviceInfo and using range_bins, range_bin_min and range_bin_max, as they might change with future versions of the radar unit.
RaDeKL Radar API Programmer’s Guide 28 RaDeKL_StartContinuousDetection Start continuous detection, with a new detection occurring each interval set with RaDeKL_SetInterval. This function is intended to be used in conjunction with RaDeKL_ReadDetectionData and RaDeKL_StopContinuousDetection.
RaDeKL Radar API Programmer’s Guide 29 Example 2: Process continuous radar detections until user stops. This requires 2 threads, one to handle the GUI and the other to read and process the radar range bin data. // Global data RaDeKL_HANDLE HANDLE BOOL handle; g_hthread; running = false; >>> Thread 1 (GUI): // Assume we have an open radar with a valid handle AND a secondary thread // User signals to START continuous detection status = RaDeKL_StartContinuousDetection (handle); // Check status . . .
RaDeKL Radar API Programmer’s Guide 30 RaDeKL_StopContinuousDetection Stop continuous detection. This function is intended to be used in conjunction with RaDeKL_StartContinuousDetection and RaDeKL_ReadDetectionData. Format: ULONG RaDeKL_StopContinuousDetection (RaDeKL_HANDLE handle); Parameters: handle RaDeKL_HANDLE as returned by a call to RaDeKL_OpenRadar. Return Value: RADEKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes.
RaDeKL Radar API Programmer’s Guide 31 RaDeKL_ReadDetectionData Read and return the range bin data of a single detection in continuous mode. This function is intended to be used in conjunction with RaDeKL_StartContinuousDetection and RaDeKL_StopContinuousDetection.
RaDeKL Radar API Programmer’s Guide 32 Part VI: Radar Register Functions RaDeKL_WriteCheckRegister Note: This is a low-level function and should only be used if you are familiar with the RaDeKL Radar registers and their layouts. Normal operation of the RaDeKL Radar should require only the use of the high-level functions described above. Write a data BYTE into one of RaDeKL Radar’s registers. The data is then read back and compared to ensure that it was, in fact, written correctly.
RaDeKL Radar API Programmer’s Guide 33 RaDeKL_WriteRegister Note: This is a low-level function and should only be used if you are familiar with the RaDeKL Radar registers and their layouts. Normal operation of the RaDeKL Radar should require only the use of the high-level functions described above. Write a data BYTE into one of RaDeKL Radar’s registers. No checking is performed to see if the data was written correctly, making this function suitable for write-only registers.
RaDeKL Radar API Programmer’s Guide 34 RaDeKL_ReadRegister Note: This is a low-level function and should only be used if you are familiar with the RaDeKL Radar registers and their layouts. Normal operation of the RaDeKL Radar should require only the use of the high-level functions described above. Read a sequence of one or more RaDeKL Radar registers.
RaDeKL Radar API Programmer’s Guide 35 Part VII: Low-Level Data I/O Functions RaDeKL_SendCommand Note: This is a low-level function and should only be used if you are familiar with the RaDeKL Radar I/O features. Normal operation of the RaDeKL Radar should require only the use of the highlevel functions described above. Send a command to the RaDeKL Radar.
RaDeKL Radar API Programmer’s Guide 36 RaDeKL_ReceiveResponse Note: This is a low-level function and should only be used if you are familiar with the RaDeKL Radar I/O features. Normal operation of the RaDeKL Radar should require only the use of the highlevel functions described above. Receive a response from the radar by reading a specified number of bytes. There are two types of responses, returned register values and a set of range bins resulting from a detection request.
RaDeKL Radar API Programmer’s Guide 37 Example 1: Read the value of the register at address 7 (REGISTER_DAC1). ULONG DWORD RaDeKL_HANDLE BYTE BYTE status; bytes_received; handle; cmd[5] = {CMD_READ, 0, REGISTER_DAC1, 1, CMD_TERM}; response [1024]; // Make this sufficiently large // Assume we have an open radar with a valid handle status = RaDeKL_SendCommand (handle, cmd, 5); // Check status . . . status = RaDeKL_ReceiveResponse (handle, response, 4, &bytes_received); // Check status . . .
RaDeKL Radar API Programmer’s Guide 38 Part VIII: Appendix RaDeKL_DEVICEINFO Field Definitions The following list provides a list of the fields available in the RaDeKL_DEVICEINFO structure, obtained by calling RaDeKL_GetDeviceInfo. For the actual source-code of the structure definition, see the RaDeKLAPI.H Header File Listing at the end of the Appendix.
RaDeKL Radar API Programmer’s Guide 39 RaDeKL Radar Register Definitions The following list provides the current definition of the RaDeKL Radar registers. These definitions may change with future versions of the radar device.
RaDeKL Radar API Programmer’s Guide 40 All Registers contain one 8-bit binary value (1 byte), allowing for a range between 0 and 255 (decimal) or 0x00 and 0xFF (hexadecimal). Register Data Definitions: Register Name Address Description REGISTER_ID_VERS 0 Read-only register. Writing to this register has no effect. High-order 4-bits contains major version number and low-order 4-bits the minor version number.
RaDeKL Radar API Programmer’s Guide 41 RaDeKLAPI.H Header File Listing //############################################################################## //############################################################################## // // RaDeKL API.h // // (header file) // // The RaDeKL API provides access to the functions of the Multispectral // Solutions, Inc. (MSSI) RaDeKL Radar product. Please refer to the // "RaDeKL Radar API Programmer's Guide" for details.
RaDeKL Radar API Programmer’s Guide #define #define #define #define #define #define RaDeKL_BAD_THRESHOLD RaDeKL_BAD_TX_ATTEN RaDeKL_BAD_RX_ATTEN RaDeKL_BAD_RANGE_DELAY RaDeKL_BAD_INTERVAL RaDeKL_UNKNOWN_RESOLUTION 42 207 208 209 210 211 212 // Command codes #define CMD_READ #define CMD_WRITE #define CMD_TERM #define CMD_DATA 114 119 255 234 // Detection register codes #define DETECT_SINGLE #define DETECT_START_CONTINUOUS #define DETECT_STOP_CONTINUOUS 1 4 0 // RF-Control register codes #define FIRM
RaDeKL Radar API Programmer’s Guide #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define REGISTER_DAC16 REGISTER_DAC17 REGISTER_DAC18 REGISTER_DAC19 REGISTER_DAC20 REGISTER_DAC21 REGISTER_DAC22 REGISTER_DAC23 REGISTER_DAC24 REGISTER_DAC25 REGISTER_DAC26 REGISTER_DAC27 REGISTER_DAC28 REGISTER_DAC29 REGISTER_DAC30 REGISTER_DAC31 REGISTER_DAC32 REGISTER_MAX 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 39 // //
RaDeKL Radar API Programmer’s Guide 44 // // // Forward declarations // // // Status reporting utilities char *RaDeKL_GetStatusText (ULONG errcode); ULONG RaDeKL_GetAPIVersion (); // RaDeKL Radar management functions ULONG RaDeKL_ListRadars (DWORD *cnt, char ***serial_numbers, char ***descriptions); void RaDeKL_ListRadarsCleanup (char **list); ULONG RaDeKL_OpenRadar (RaDeKL_HANDLE *handle, char *serial_number); ULONG RaDeKL_CloseRadar (RaDeKL_HANDLE handle); ULONG RaDeKL_FlushIO (RaDeKL_HANDLE handle); UL
