Zebra Technologies RADEKL Radar Development Kit User Manual Programmers Guide

Zebra Technologies Corporation Radar Development Kit Programmers Guide

UserManual.wiki >

Zebra Technologies >

RADEKL User Manual >

Programmers Guide

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. These limits are designed to provide reasonable protection against harmful interference in a residential installation. This equipment generates, uses and can radiate radio frequency energy and, if not installed and used in accordance with the instructions, may cause harmful interference to radio communications. However, there is no guarantee that interference will not occur in a particular installation. If this equipment does cause harmful interference to radio or television reception, which can be determined by turning the equipment off and on, the user is encouraged to try to correct the interference by one or more of the following measures: —Reorient or relocate the receiving antenna. —Increase the separation between the equipment and receiver. —Connect the equipment into an outlet on a circuit different from that to which the receiver is connected. —Consult the dealer or an experienced radio/TV technician for help.

RaDeKL Radar API Programmer’s Guide I © Multispectral Solutions, Inc. 2006 Table of Contents Part I: Welcome to the RaDeKL Radar API....................................................................1 Introduction.................................................................................................................................... 1 USB Driver Installation.................................................................................................................. 1 Programming Notes ...................................................................................................................... 3 Usage Warnings............................................................................................................................. 4 Part II: Status Formatting Functions .............................................................................5 RaDeKL_GetStatusText ................................................................................................................ 5 RaDeKL_GetAPIVersion................................................................................................................ 7 Part III: Radar Management Functions..........................................................................8 RaDeKL_ListRadars ...................................................................................................................... 8 RaDeKL_ListRadarsCleanup...................................................................................................... 10 RaDeKL_OpenRadar ...................................................................................................................11 RaDeKL_CloseRadar................................................................................................................... 12 RaDeKL_GetDeviceInfo...............................................................................................................13 RaDeKL_ResetRadar...................................................................................................................14 RaDeKL_FlushIO .........................................................................................................................15 Part IV: Radar Parameter Functions............................................................................16 RaDeKL_SetThresholds.............................................................................................................. 16 RaDeKL_GetThresholds .............................................................................................................17 RaDeKL_SetTransmitAttenuation.............................................................................................. 18 RaDeKL_GetTransmitAttenuation .............................................................................................19 RaDeKL_SetReceiveAttenuation ...............................................................................................20 RaDeKL_GetReceiveAttenuation...............................................................................................21 RaDeKL_SetRangeDelay.............................................................................................................22 RaDeKL_GetRangeDelay ............................................................................................................23 RaDeKL_SetInterval ....................................................................................................................24 RaDeKL_GetInterval....................................................................................................................25 RaDeKL_SimulatorMode.............................................................................................................26 Part V: Radar Detection Functions ..............................................................................27 RaDeKL_DetectSingle.................................................................................................................27 RaDeKL_StartContinuousDetection.......................................................................................... 28 RaDeKL_StopContinuousDetection .......................................................................................... 30 RaDeKL_ReadDetectionData...................................................................................................... 31

RaDeKL Radar API Programmer’s Guide II © Multispectral Solutions, Inc. 2006 Part VI: Radar Register Functions ...............................................................................32 RaDeKL_WriteCheckRegister ....................................................................................................32 RaDeKL_WriteRegister ...............................................................................................................33 RaDeKL_ReadRegister................................................................................................................34 Part VII: Low-Level Data I/O Functions........................................................................35 RaDeKL_SendCommand ............................................................................................................35 RaDeKL_ReceiveResponse........................................................................................................ 36 Part VIII: Appendix ........................................................................................................38 RaDeKL_DEVICEINFO Field Definitions....................................................................................38 RaDeKL Radar Register Definitions ..........................................................................................39 RaDeKLAPI.H Header File Listing..............................................................................................41

RaDeKL Radar API Programmer’s Guide 2 © Multispectral Solutions, Inc. 2006 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. Note: The additional USB device installed represents an unused internal port on the USB chip. This port is not used by RaDeKL Radar and can be entirely ignored. However, during driver installation, Windows will detect this unused port and insist on installing a driver for it. 9. The RaDeKL Radar is now ready for use. The driver needs to be installed only once for each PC. If it ever needs to be upgraded, use the Windows Device Manager, ensuring that the radar device is physically plugged in and powered up.

RaDeKL Radar API Programmer’s Guide 3 © Multispectral Solutions, Inc. 2006 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.h in your C program: #include "RaDeKLAPI.h" Note: RaDeKLAPI.h implicitly includes FTD2XX.h 3. Include RaDeKLAPI.lib in your project link command: In Visual C++ (6.0), click Project > Settings. Select “All Configurations” and “Link”. Add RaDeKLAPI.lib to the “Object/library modules” as follows: Note: The FTD2XX.lib library is already included in RaDeKLAPI.lib and therefore does not need to be included in your project link, nor does it need to be present in your development environment folder. RaDeKLAPI.lib is entirely self-contained. You can now use the RaDeKL API functions to operate the radar unit. The next section documents the usage of the various RaDeKL API functions available.

RaDeKL Radar API Programmer’s Guide 4 © Multispectral Solutions, Inc. 2006 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 low-level register write to do the same). Do not issue any other register read and/or write commands (or high-level functions that read/write registers), as this will interfere with the continuous data stream presented in continuous detection mode. Note: most functions that update (write) RaDeKL registers attempt to read the data back to ensure that it was written correctly. Therefore any write-register function (RaDeKL_SetXxxxx) will result in a read after write, which will interfere with an ongoing continuous detection, producing unpredictable results (most likely resulting in an input/output error). If a register must be updated, please first stop continuous detection mode, change the register value and then restart continuous detection mode. 2. When operating the RaDeKL Radar in continuous detection mode and an error occurs (i.e. the return value of the function called, if specified, is not equal RaDeKL_OK), it is up to the caller to: a. Attempt to stop continuous detection mode on the radar unit by issuing a call to RaDeKL_StopContinuousDetection. Depending on the specific error, it might not be possible to actually communicate this command to the radar. The return code of this call should therefore be ignored in this case only. b. Ensure that the user interface or GUI appropriately shows that the radar is no longer operating in continuous mode. This may entail updating indicators or graying out buttons. c. In many error cases it may be necessary to close (if possible) and re-open the radar device in order to re-establish communications with the unit (using RaDeKL_CloseRadar and RaDeKL_OpenRadar, respectively). In some (rare) cases the unit may have to be either power-cycled or unplugged and re-connected to the USB cable. Contrary to the FTDI USB Chip documentation, this cannot always be done under program control.

RaDeKL Radar API Programmer’s Guide 5 © Multispectral Solutions, Inc. 2006 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. Return Value: Pointer to a null-terminated character string containing the status description. Possible Status Codes: Symbol Value Description Text FTDI specific status codes RaDeKL_OK 0 Operation completed successfully RaDeKL_INVALID_HANDLE 1 Invalid handle passed to function RaDeKL_DEVICE_NOT_FOUND 2 Requested device not found RaDeKL_DEVICE_NOT_OPENED 3 Specified device not open RaDeKL_IO_ERROR 4 Input/output error RaDeKL_INSUFFICIENT_RESOURCES 5 Insufficient resources to complete operation RaDeKL_INVALID_PARAMETER 6 Invalid parameter passed to function RaDeKL_INVALID_BAUD_RATE 7 Invalid baud rate specified RaDeKL_DEVICE_NOT_OPENED_FOR_ERASE 8 Specified device not open for erase RaDeKL_DEVICE_NOT_OPENED_FOR_WRITE 9 Specified device not open for write RaDeKL_FAILED_TO_WRITE_DEVICE 10 Failed to write to specified device RaDeKL_EEPROM_READ_FAILED 11 EEPROM read failed RaDeKL_EEPROM_WRITE_FAILED 12 EEPROM write failed RaDeKL_EEPROM_ERASE_FAILED 13 EEPROM erase failed RaDeKL_EEPROM_NOT_PRESENT 14 EEPROM not present RaDeKL_EEPROM_NOT_PROGRAMMED 15 EEPROM not programmed RaDeKL_INVALID_ARGS 16 Invalid arguments passed to function RaDeKL_NOT_SUPPORTED 17 Operation not supported RaDeKL_OTHER_ERROR 18 USB unknown error RaDeKL API specific status codes RaDeKL_READ_TIMEOUT 201 Read from radar has timed out RaDeKL_WRITE_TIMEOUT 202 Write to radar has timed out RaDeKL_INCORRECT_SERIAL_NUMBER 203 Serial number opened does not match request RaDeKL_WRITE_REGISTER_FAILED 204 Register write failed RaDeKL_READ_REGISTER_FAILED 205 Register read failed RaDeKL_READ_DETECTION_FAILED 206 Detection data read failed RaDeKL_BAD_THRESHOLD 207 Invalid threshold(s) specified RaDeKL_BAD_TX_ATTEN 208 Invalid transmit attenuation specified RaDeKL_BAD_RX_ATTEN 209 Invalid receive attenuation specified RaDeKL_BAD_RANGE_DELAY 210 Invalid range delay specified RaDeKL_BAD_INTERVAL 211 Invalid interval specified RaDeKL_UNKNOWN_RESOLUTION 212 Radar has an unknown resolution

$RaDeKL Radar API Programmer’s Guide 6 © Multispectral Solutions, Inc. 2006 Example: Make a RaDeKL API function call to list available devices and display an error message if the call failed. ULONG status; DWORD numdevs; char **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;$

$RaDeKL Radar API Programmer’s Guide 7 © Multispectral Solutions, Inc. 2006 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. Format: ULONG RaDeKL_GetAPIVersion (); Parameters: <none> Return Value: ULONG (32 bits) with the major version number in the high-order WORD (16 bits) and the minor version number in the low-order WORD (16 bits). Example: Get and display the major and minor version numbers of this API. ULONG version; WORD major_version; WORD minor_version; version = RaDeKL_GetAPIVersion (); major_version = (WORD)((version >> 16) & 0xFFFF); minor_version = (WORD)(version & 0xFFFF); printf (“This API is version %d.%d\n”, major_version, minor_version);$

RaDeKL Radar API Programmer’s Guide 8 © Multispectral Solutions, Inc. 2006 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. The serial number is unique to each unit sold, whereas the description string is unique to a particular version (or model) of RaDeKL Radars and may change with future versions. Format: ULONG RaDeKL_ListRadars (DWORD *numdevs, char ***serial_numbers, char ***descriptions); Parameters: numdevs Pointer to a DWORD to receive the device count. This may be NULL, in which case no device count is returned. serial_numbers Pointer to a pointer to a (null-terminated) list of character strings to receive the serial numbers of the connected devices. (*numdevs) should initially be NULL, as the function allocates the list and the individual strings. See example for clarification. If NULL is passed as numdev, no serial numbers are returned. descriptions Pointer to a pointer to a (null-terminated) list of character strings to receive the descriptions of the connected devices. (*descriptions) should initially be NULL, as the function allocates the list and the individual strings. See example for clarification. If NULL is passed as descriptions, no descriptions are returned. Return Value: RaDeKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes. Remarks: This function will automatically allocate the storage required for the serial number and description lists and the associated character strings. If valid pointers are passed in, the existing storage (as allocated by a previous call to RaDeKL_ListRadars) will first be de-allocated before the new lists are allocated. This way the designer does not need to bother maintaining these lists (i.e. simplifying re-scanning of connected radar units), as long as the pointers are initially set to NULL. See examples below for clarification. Any remaining lists will be de-allocated when the program terminates. If the design requires an explicit de-allocation of the lists, use RaDeKL_ListRadarsCleanup described below.

$RaDeKL Radar API Programmer’s Guide 9 © Multispectral Solutions, Inc. 2006 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: %s\n”, i, snum[i], desc[i]); Example 2: Alternately, if we don’t care about the number of devices or their descriptions, the following code segment will return only the (null-terminated) list of serial numbers: ULONG status; static char **snum = NULL; // or make this global char **s; status = RaDeKL_ListRadars (NULL, &snum, NULL); if (status != RaDeKL_OK) { printf (“Unable to list devices: %s\n”, RaDeKL_GetStatusText (status)); return; } for (s = snum; *s; s++) printf (“Serial Number: %s\n”, *s);$

$RaDeKL Radar API Programmer’s Guide 10 © Multispectral Solutions, Inc. 2006 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. Format: void RaDeKL_ListRadarsCleanup (char **list); Parameters: list Pointer to a (null-terminated) list of character strings to de-allocate. Return Value: No return value. This function cannot fail. Example: 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: %s\n”, i, snum[i], desc[i]); // De-allocate the lists RaDeKL_ListRadarsCleanup (snum); snum = NULL; RaDeKL_ListRadarsCleanup (desc); snum = NULL;$

$RaDeKL Radar API Programmer’s Guide 11 © Multispectral Solutions, Inc. 2006 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. All further operations on that device will use this handle. serial_number Pointer to a (null-terminated) character string containing the serial number of the device to open. A list of all available RaDeKL Radar devices and their serial numbers is obtained by calling RaDeKL_ListRadars. Return Value: RaDeKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes. Example: Open (and close) the first radar unit found. ULONG status; DWORD numdevs; static char **snum = NULL, **desc = NULL; // or make these global static RaDeKL_HANDLE handle = NULL; // or make this global status = RaDeKL_ListRadars (&numdevs, &snum, &desc); if (status != RaDeKL_OK) { printf (“Unable to list devices: %s\n”, RaDeKL_GetStatusText (status)); return; } if (numdevs == 0) { printf (“No devices available\n”); return; } status = RaDeKL_OpenRadar (&handle, snum[0]); if (status != RADEKL_OK) { printf (“Open failed: %s\n”, RaDeKL_GetStatusText (status)); return; } // Do some work and then close the radar and set the handle to NULL RaDeKL_CloseRadar (handle); handle = NULL;$

RaDeKL Radar API Programmer’s Guide 12 © Multispectral Solutions, Inc. 2006 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. Remarks: It is highly recommended that you set the handle to NULL after calling this function to avoid accidental use of a closed handle. See the example for RaDeKL_OpenRadar above. Example: See the example for RaDeKL_OpenRadar above.

$RaDeKL Radar API Programmer’s Guide 13 © Multispectral Solutions, Inc. 2006 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. See RaDeKL_GetStatusText for codes. Remarks: RaDeKL_GetDeviceInfo should be called after RaDeKL_OpenRadar to obtain device-version-specific information. The currently available RaDeKL units all have a resolution of 1 foot (= 2), 256 range bins (with a data range of 0 to 32), 32 DAC threshold registers (with a data range of 20 to 227). This may change in future units and the info returned by RaDeKL_GetDeviceInfo should be used in your application instead of hard-coding these values. Example: List device-specific information. ULONG status; RaDeKL_HANDLE handle; RaDeKL_DEVICEINFO info; // Assume we have an open radar with a valid handle status = RaDeKL_GetDeviceInfo (handle, &info); // Check status . . . // Print information printf (“Serial number: %s\n”, info.ft_serial_number);// String printf (“Description: %s\n”, info.ft_description); // String printf (“Vendor ID: %4X\n”, info.ft_vendor_id); // 16-bit hex printf (“Product ID: %4X\n”, info.ft_product_id); // 16-but hex printf (“Resolution: %d\n”, info.resolution); // 1 = 6-inch, 2 = 1-foot printf (“Range bins: %d\n”, info.range_bins); // Currently 256 printf (“Range bin max: %d\n”, info.range_bin_max); // Currently 32 printf (“Thresholds: %d\n”, info.thresholds); // Currently 32 printf (“Threshold min: %d\n”, info.threshold_min); // Currently 20 printf (“Threshold max: %d\n”, info.threshold_max); // Currently 227 printf (“Version: v%d.%d\n”, info.version_id_major, info.version_id_minor);$

RaDeKL Radar API Programmer’s Guide 14 © Multispectral Solutions, Inc. 2006 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. It is strongly recommended to re-send all pertinent register values to the radar after calling this function to ensure that the application and the actual radar unit are in sync. Format: ULONG RaDeKL_ResetRadar (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. Example: Perform a reset on a RaDeKL Radar device. ULONG status; RaDeKL_HANDLE handle; // Assume we have an open radar with a valid handle status = RaDeKL_ResetRadar (handle); // Check status . . .

RaDeKL Radar API Programmer’s Guide 15 © Multispectral Solutions, Inc. 2006 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. Format: ULONG RaDeKL_FlushIO (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. Example: Flush the USB transmit and receive ports. ULONG status; RaDeKL_HANDLE handle; // Assume we have an open radar with a valid handle status = RaDeKL_FlushIO (handle); // Check status . . .

$RaDeKL Radar API Programmer’s Guide 16 © Multispectral Solutions, Inc. 2006 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. The default values for the 32 DAC Threshold registers start at 20 (DAC 1) and are evenly spread up to 227 (DAC 32). Format: ULONG RaDeKL_SetThresholds (RaDeKL_HANDLE handle, BYTE *thresholds); Parameters: handle RaDeKL_HANDLE as returned by a call to RaDeKL_OpenRadar. thresholds A BYTE array of sufficient size to hold all DAC Threshold register values (currently 32). Return Value: RADEKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes. Example: Add 10 to all DAC Threshold values (assuring that the max is not exceeded). ULONG status; RaDeKL_HANDLE handle; RaDeKL_DEVICEINFO info; BYTE thresholds[256]; // Declare a reasonably large number // Assume we have an open radar with a valid handle status = RaDeKL_GetDeviceInfo (handle, &info); // Check status . . . // Get the current DAC Threshold values status = RaDeKL_GetThresholds (handle, thresholds); // Check status . . . // Add 10 to ALL registers (limited by threshold_max) and print the values for (i = 0; i < info.thresholds; i++) { thresholds[i] = min (thresholds[i]+10, info.threshold_max); printf (“DAC Threshold register %2d changed to %d\n”, i, thresholds[i]); } // Set the modified DAC Threshold values status = RaDeKL_SetThresholds (handle, thresholds); // Check status . . .$

RaDeKL Radar API Programmer’s Guide 17 © Multispectral Solutions, Inc. 2006 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. Format: ULONG RaDeKL_GetThresholds (RaDeKL_HANDLE handle, BYTE *thresholds); Parameters: handle RaDeKL_HANDLE as returned by a call to RaDeKL_OpenRadar. thresholds A BYTE array of sufficient size to hold all DAC Threshold register values (currently 32). Return Value: RADEKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes. Example: See the example given for RaDeKL_SetThresholds above.

RaDeKL Radar API Programmer’s Guide 18 © Multispectral Solutions, Inc. 2006 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. Format: ULONG RaDeKL_SetTransmitAttenuation (RaDeKL_HANDLE handle, BYTE attenuation); Parameters: handle RaDeKL_HANDLE as returned by a call to RaDeKL_OpenRadar. attenuation A BYTE indicating the attenuation to be set. Permissible attenuation values are in the range from 0 to 63. Reference values are: Value Attenuation 63 0 dB (default) 57 -3 dB 51 -6 dB 43 -10 dB The attenuation (in dB) or the register value are calculated as: attenuation_dB = (register_value – 63) / 2 and register_value = (2 * attenuation_dB) + 63 Note: attenuations are usually negative values! Attenuation_dB in the above calculations must therefore be a negative number. Return Value: RADEKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes. Example: Set the TRANSMIT ATTENUATION register to a value of 33 (-10 dB). ULONG status; RaDeKL_HANDLE handle; // Assume we have an open radar with a valid handle status = RaDeKL_SetTransmitAttenuation (handle, 33); // Check status . . .

$RaDeKL Radar API Programmer’s Guide 19 © Multispectral Solutions, Inc. 2006 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. Format: ULONG RaDeKL_GetTransmitAttenuation (RaDeKL_HANDLE handle, BYTE *attenuation); Parameters: handle RaDeKL_HANDLE as returned by a call to RaDeKL_OpenRadar. attenuation Pointer to a BYTE to receive the attenuation value. Possible attenuation values are in the range from 0 to 63. Reference values are: Value Attenuation 63 0 dB (default) 57 -3 dB 51 -6 dB 43 -10 dB The attenuation (in dB) or the register value are calculated as: attenuation_dB = (register_value – 63) / 2 and register_value = (2 * attenuation_dB) + 63 Note: attenuations are usually negative values! Attenuation_dB in the above calculations must therefore be a negative number. Return Value: RADEKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes. Example: Read the TRANSMIT ATTENUATION register and display its value. ULONG status; RaDeKL_HANDLE handle; BYTE attenuation; // Assume we have an open radar with a valid handle status = RaDeKL_GetTransmitAttenuation (handle, &attenuation); // Check status . . . printf (“The TRANSMIT ATTENUATION is currently set to %d\n”, attenuation);$

RaDeKL Radar API Programmer’s Guide 20 © Multispectral Solutions, Inc. 2006 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. Format: ULONG RaDeKL_SetReceiveAttenuation (RaDeKL_HANDLE handle, BYTE attenuation); Parameters: handle RaDeKL_HANDLE as returned by a call to RaDeKL_OpenRadar. attenuation A BYTE indicating the attenuation to be set. Permissible attenuation values are in the range from 0 to 255. Reference values are: Value Attenuation 0 0 dB (default) 31 -5 dB 81 -10 dB 125 -15 dB 155 -20 dB 180 -30 dB For the receive attenuation there is no function to convert between register value and attenuation. The above values are derived from experimentation. The user may use any register value between 0 and 255 and use the above table as a rough guide for the resulting attenuation. Return Value: RADEKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes. Example: Set the RECEIVE ATTENUATION register to a value of 91 (-10 dB). ULONG status; RaDeKL_HANDLE handle; // Assume we have an open radar with a valid handle status = RaDeKL_SetReceiveAttenuation (handle, 91); // Check status . . .

$RaDeKL Radar API Programmer’s Guide 21 © Multispectral Solutions, Inc. 2006 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. Format: ULONG RaDeKL_GetReceiveAttenuation (RaDeKL_HANDLE handle, BYTE *attenuation); Parameters: handle RaDeKL_HANDLE as returned by a call to RaDeKL_OpenRadar. attenuation Pointer to a BYTE to receive the attenuation value. Possible attenuation values are in the range from 0 to 255. Reference values are: Value Attenuation 0 0 dB (default) 31 -5 dB 81 -10 dB 125 -15 dB 155 -20 dB 180 -30 dB For the receive attenuation there is no function to convert between register value and attenuation. The above values are derived from experimentation. The user may use any register value between 0 and 255 and use the above table as a rough guide for the resulting attenuation. Return Value: RADEKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes. Example: Read the RECEIVE ATTENUATION register and display its value. ULONG status; RaDeKL_HANDLE handle; BYTE attenuation; // Assume we have an open radar with a valid handle status = RaDeKL_GetReceiveAttenuation (handle, &attenuation); // Check status . . . printf (“The RECEIVE ATTENUATION is currently set to %d\n”, attenuation);$

$RaDeKL Radar API Programmer’s Guide 22 © Multispectral Solutions, Inc. 2006 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. Format: ULONG RaDeKL_SetRangeDelay (RaDeKL_HANDLE handle, DWORD delay_feet, DWORD *actual_delay_feet); Parameters: handle RaDeKL_HANDLE as returned by a call to RaDeKL_OpenRadar. delay_feet A DWORD indicating the requested delay value in feet. Do not use a value larger than the maximum range of the radar device. actual_delay_feet Pointer to a DWORD to receive the actual delay set. This may be NULL, in which case no actual delay is returned. The actual delay may differ from the requested one, since the hardware allows delays only in certain increments (8 feet in the current model). If necessary, the requested value is rounded down to the nearest increment. Return Value: RADEKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes. Example: Set the RangeDelay to 32 feet. ULONG status; RaDeKL_HANDLE handle; DWORD actual; // Assume we have an open radar with a valid handle status = RaDeKL_SetRangeDelay (handle, 32, &actual); // Check status . . . printf (“Range Delay set to %d feet\n”, actual);$

$RaDeKL Radar API Programmer’s Guide 23 © Multispectral Solutions, Inc. 2006 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. Example: Read the RangeDelay and display its value. ULONG status; RaDeKL_HANDLE handle; DWORD delay; // Assume we have an open radar with a valid handle status = RaDeKL_GetRangeDelay (handle, &delay); // Check status . . . printf (“The DELAY is currently set to %d feet\n”, delay);$

RaDeKL Radar API Programmer’s Guide 24 © Multispectral Solutions, Inc. 2006 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. 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. Format: ULONG RaDeKL_SetInterval (RaDeKL_HANDLE handle, BYTE interval); Parameters: handle RaDeKL_HANDLE as returned by a call to RaDeKL_OpenRadar. interval A BYTE indicating the requested interval. Permissible interval values are: Symbolic Constant Duration Value INTERVAL_1_SEC 1 second 0 INTERVAL_500_MSEC 500 milliseconds 1 INTERVAL_250_MSEC 250 milliseconds 2 INTERVAL_100_MSEC 100 milliseconds 3 INTERVAL_50_MSEC (default) 50 milliseconds 4 Return Value: RADEKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes. Example: Set the continuous detection interval to 100 milliseconds. ULONG status; RaDeKL_HANDLE handle; // Assume we have an open radar with a valid handle status = RaDeKL_SetInterval (handle, INTERVAL_100_MS); // Check status . . .

$RaDeKL Radar API Programmer’s Guide 25 © Multispectral Solutions, Inc. 2006 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. Format: ULONG RaDeKL_GetInterval (RaDeKL_HANDLE handle, BYTE *interval); Parameters: handle RaDeKL_HANDLE as returned by a call to RaDeKL_OpenRadar. interval Pointer to a BYTE to receive the interval value. Possible interval values are: Symbolic Constant Duration Value INTERVAL_1_SEC 1 second 0 INTERVAL_500_MSEC 500 milliseconds 1 INTERVAL_250_MSEC 250 milliseconds 2 INTERVAL_100_MSEC 100 milliseconds 3 INTERVAL_50_MSEC (default) 50 milliseconds 4 Return Value: RADEKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes. Example: Read the continuous detection interval and display its value. ULONG status; RaDeKL_HANDLE handle; BYTE interval; // Assume we have an open radar with a valid handle status = RaDeKL_GetInterval (handle, &interval); // Check status . . . printf (“The interval for continuous detection is currently set to “); switch (interval) { case INTERVAL_1_SEC: printf (“1 second\n”); break; case INTERVAL_500_MS: printf (“500 ms\n”); break; case INTERVAL_250_MS: printf (“250 ms\n”); break; case INTERVAL_100_MS: printf (“100 ms\n”); break; case INTERVAL_50_MS: printf (“50 ms\n”); break; }$

$RaDeKL Radar API Programmer’s Guide 26 © Multispectral Solutions, Inc. 2006 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. In situations where an actual radar unit is unavailable for testing of the software, simulation mode may be enabled, resulting in the proper and expected behavior of all API functions with these considerations: 1. RaDeKL_ListRadars will detect four simulated radar units with serial numbers “SIM001”, “SIM002”, “SIM003” and “SIM004” and a description of “RaDeKL Simulator”. 2. Any RaDeKL API function may be called for these simulated radar units, including detection functions. 3. Detection will result in range bin data representing a dampened sine wave, rotating over time (or successive detections) for SIM001 and other diagnostic waveforms for SIM002 - SIM004. 4. Since there is no physical communication to an actual radar unit, some error paths in the program may not be sufficiently tested using Simulator Mode. Format: bool RaDeKL_SimulatorMode (bool enable); Parameters: enable Flag to enable (true) or disable (false) the RaDeKL Simulator Mode. Return Value: The previous value of the RaDeKL Simulator Mode. Remarks: Normally, this function would be called at the start of your program, before any potential radar units have been opened. However, if a program switches dynamically between Simulator and actual radar modes, ensure that any open radar devices (real or simulated) are closed first using RaDeKL_CloseRadar. Toggling Simulator Mode will cause RaDeKL_ListRadars to return a different list of available radar devices. Therefore a call to RaDeKL_SimulatorMode should always be followed by a call to RaDeKL_ListRadars to refresh the list of available devices. Example: Enable the RaDeKL Simulator mode. ULONG status; DWORD numdevs; static char **snum = NULL, **desc = NULL; // or make these global RaDeKL_SimulatorMode (true); printf (“The RaDeKL Simulation Mode is now enabled\n”); status = RaDeKL_ListRadars (&numdevs, &snum, &desc); // Check status . . .$

$RaDeKL Radar API Programmer’s Guide 27 © Multispectral Solutions, Inc. 2006 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. Format: ULONG RaDeKL_DetectSingle (RaDeKL_HANDLE handle, BYTE *data); Parameters: handle RaDeKL_HANDLE as returned by a call to RaDeKL_OpenRadar. data Pointer to a BYTE array to receive the radar return data. Note: This array is not null-terminated, since zeroes may appear in the data. Note: the size of this array and the maximum value for each range bin are currently fixed at 256 and 32, respectively, but might change with future versions. See notes above. Return Value: RADEKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes. Example: Initiate a single detection and print the range bin data. ULONG status, i; RaDeKL_HANDLE handle; RaDeKL_DEVICEINFO info; BYTE data[2048]; // Make this sufficiently large // Assume we have an open radar with a valid handle status = RaDeKL_GetDeviceInfo (handle, &info); // Check status . . . status = RaDeKL_DetectSingle (handle, data); // Check status . . . for (i = 0; i < info.range_bins; i++) printf (“Range bin [%3d] contains: %d\n”, i, data[i]);$

$RaDeKL Radar API Programmer’s Guide 28 © Multispectral Solutions, Inc. 2006 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. Note: Unless there is an initially known fixed number of detections to be performed, continuous detection may require a separate thread to execute RaDeKL_ReadDetectionData, or otherwise it may be impossible to issue RaDeKL_StopContinuousDetection since RaDeKL_ReadDetectionData will be in a tight loop waiting for the next detection data to arrive. See examples below for clarification. Note: While in continuous detection mode, do not issue any other register read/write functions (except RaDeKL_StopContinuousDetection) as their processing will interfere with the continuous data stream returned by the RaDeKL Radar device. See Usage Warnings towards the top of this document for clarification. Format: ULONG RaDeKL_StartContinuousDetection (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. Example 1: Process 100 continuous radar detections. ULONG status, count; RaDeKL_HANDLE handle; BYTE data[2048]; // Make this sufficiently large // Assume we have an open radar with a valid handle status = RaDeKL_StartContinuousDetection (handle); // Check status . . . count = 100; while (count--) { status = RaDeKL_ReadDetectionData (handle, data); // Check status . . . // Do something with the data . . . // } status = RaDeKL_StopContinuousDetection (handle); // Check status . . . // Flush the buffers status = RaDeKL_FlushIO (handle); // Check status . . .$

$RaDeKL Radar API Programmer’s Guide 29 © Multispectral Solutions, Inc. 2006 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; HANDLE g_hthread; BOOL 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 . . . // Wake up secondary thread running = true; ResumeThread (g_hthread); // Return to the GUI message loop . . . // User signals to STOP continuous detection running = false; status = RaDeKL_StopContinuousDetection (handle); // Check status . . . // Flush the buffers status = RaDeKL_FlushIO (handle); // Check status . . . >>> Thread 2 (read and process loop): ULONG status; BYTE data[2048]; // Make this sufficiently large // Assume we have an open radar with a valid handle while (true) // Loop this thread forever until the program terminates { while (running) // Loop until the GUI sets running to false { status = RaDeKL_ReadDetectionData (handle, data); // Check status. Ignore a timeout if running is false if ((status == RADEKL_OK) || ((!running) && (status == RADEKL_READ_TIMEOUT))) { // Do something with the data . . . } else { printf (“Bad read: %s\n”, RaDeKL_GetStatusText (status)); running = false; break; } } // No longer running - go to sleep SuspendThread (GetCurrentThread ()); }$

RaDeKL Radar API Programmer’s Guide 30 © Multispectral Solutions, Inc. 2006 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. Example: See the examples for RaDeKL_StartContinuousDetection above.

RaDeKL Radar API Programmer’s Guide 31 © Multispectral Solutions, Inc. 2006 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. 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. Format: ULONG RaDeKL_ReadDetectionData (RaDeKL_HANDLE handle, BYTE *data); Parameters: handle RaDeKL_HANDLE as returned by a call to RaDeKL_OpenRadar. data Pointer to a BYTE array to receive the radar return data. Note: This array is not null-terminated, since zeroes may appear in the data. Note: the size of this array and the maximum value for each range bin are currently fixed at 256 and 32, respectively, but might change with future versions. See notes for RaDeKL_DetectSingle. Return Value: RADEKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes. Example: See the examples for RaDeKL_StartContinuousDetection above.

RaDeKL Radar API Programmer’s Guide 32 © Multispectral Solutions, Inc. 2006 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. Note: This function reads the register back to ensure that it was written correctly. Do not use this function on command registers that have write-only bits (such as REGISTER_DETECT). Use RaDeKL_WriteRegister instead. Format: ULONG RaDeKL_WriteCheckRegister (RaDeKL_HANDLE handle, WORD addr, BYTE value); Parameters: handle RaDeKL_HANDLE as returned by a call to RaDeKL_OpenRadar. addr 16-bit address of the register to modify. See the appendix for register definitions. value 8-bit value to put into the requested register. Return Value: RADEKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes. Example: Write a value of 50 into register at address 8 (REGISTER_DAC1). ULONG status; RaDeKL_HANDLE handle; // Assume we have an open radar with a valid handle status = RaDeKL_WriteCheckRegister (handle, REGISTER_DAC1, 50); // Check status . . .

RaDeKL Radar API Programmer’s Guide 33 © Multispectral Solutions, Inc. 2006 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. If verification is required, use RaDeKL_WriteCheckRegister instead. Format: ULONG RaDeKL_WriteRegister (RaDeKL_HANDLE handle, WORD addr, BYTE value); Parameters: handle RaDeKL_HANDLE as returned by a call to RaDeKL_OpenRadar. addr 16-bit address of the register to modify. See the appendix for register definitions. value 8-bit value to put into the requested register. Return Value: RADEKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes. Example: Write DETECT_SINGLE (1) into REGISTER_DETECT at address 1. This triggers a single detection and the transmission of the range bin data. ULONG status; RaDeKL_HANDLE handle; BYTE data[2048]; // Make this sufficiently large // Assume we have an open radar with a valid handle status = RaDeKL_WriteRegister (handle, REGISTER_DETECT, DETECT_SINGLE); // Check status . . . // Read the range bin data status = RaDeKL_ReadDetectionData (handle, data); // Check status . . .

$RaDeKL Radar API Programmer’s Guide 34 © Multispectral Solutions, Inc. 2006 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. Format: ULONG RaDeKL_ReadRegister (RaDeKL_HANDLE handle, WORD addr, BYTE count, BYTE *values); Parameters: handle RaDeKL_HANDLE as returned by a call to RaDeKL_OpenRadar. addr 16-bit address of the register to modify. See the appendix for register definitions. count 8-bit count of successive registers to read. values Pointer to an BYTE-array to receive the values of the requested register(s). Return Value: RADEKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes. Example: Read and print the value stored in register REGISTER_ID_VERS (0) ULONG status; RaDeKL_HANDLE handle; BYTE version; // Assume we have an open radar with a valid handle status = RaDeKL_ReadRegister (handle, REGISTER_ID_VERS, 1, &version); // Check status . . . printf (“The version register contains %02X (major = %d, minor = %d)\n”, version, version >> 4, version & 0xF);$

$RaDeKL Radar API Programmer’s Guide 35 © Multispectral Solutions, Inc. 2006 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 high-level functions described above. Send a command to the RaDeKL Radar. The command must be a read register or a write register command in the following form: Read Register (always 5 bytes): <0x72><addr-hi><addr-lo><qty><0xFF> Write Register (always 5 bytes): <0x77><addr-hi><addr-lo><val><0xFF> Where: <addr-hi> is the high byte of the 16-bit register address. <addr-lo> is the low byte of the 16-bit register address. (See the appendix for register definitions) <qty> is an 8-bit count of registers to read (read command only). <val> is an 8-bit value to write to the register (write command only). Format: ULONG RaDeKL_SendCommand (RaDeKL_HANDLE handle, BYTE *cmd, DWORD bytes_to_send); Parameters: handle RaDeKL_HANDLE as returned by a call to RaDeKL_OpenRadar. cmd Pointer to the 5-byte command. bytes_to_send Number of bytes to write (should always be 5, unless a future version extends the I/O interface). Return Value: RADEKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes. Example: Write a value of 50 into register at address 8 (REGISTER_DAC1). ULONG status; RaDeKL_HANDLE handle; BYTE cmd[5] = {CMD_WRITE, 0, REGISTER_DAC1, 50, CMD_TERM}; // Assume we have an open radar with a valid handle status = RaDeKL_SendCommand (handle, cmd, 5); // Check status . . .$

RaDeKL Radar API Programmer’s Guide 36 © Multispectral Solutions, Inc. 2006 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 high-level 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. They are in the form: Returned register values (<number of registers requested> + 3 bytes): <addr-hi><addr-lo><data-1>...<data-n><0xFF> Range bins from detection (<number of range bins> + 4 bytes [currently 260 bytes]): <0xEA><0xEA><0xEA><bin-1>…<bin-256><0xFF> Where: <addr-hi> is the high byte of the 16-bit register address. <addr-lo> is the low byte of the 16-bit register address. (See the appendix for register definitions) <data-n> is a series of 8-bit register values (returned register values only). <bin-n> is an 8-bit value from the [n]th range bin (detection only). RaDeKL_ReceiveResponse returns the entire response, including the possible prefix (0xEA) and the terminator (0xFF). Format: ULONG RaDeKL_ReceiveResponse (RaDeKL_HANDLE handle, BYTE *response, DWORD bytes_requested, DWORD *bytes_received); Parameters: handle RaDeKL_HANDLE as returned by a call to RaDeKL_OpenRadar. response Pointer to a BYTE array to receive the data returned. bytes_requested DWORD containing the number of bytes to read. bytes_received Pointer to a DWORD to receive the number of bytes read. Return Value: RADEKL_OK (0) if successful, a non-zero status otherwise. See RaDeKL_GetStatusText for codes.

$RaDeKL Radar API Programmer’s Guide 37 © Multispectral Solutions, Inc. 2006 Example 1: Read the value of the register at address 7 (REGISTER_DAC1). ULONG status; DWORD bytes_received; RaDeKL_HANDLE handle; BYTE cmd[5] = {CMD_READ, 0, REGISTER_DAC1, 1, CMD_TERM}; BYTE 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 . . . and ensure that bytes_received == 4 printf (“The value at register DAC 1 is %d\n”, response[2]); Example 2: Issue a single detection request and read the range bins returned. ULONG status; DWORD bytes_received; RaDeKL_HANDLE handle; BYTE cmd[5] = {CMD_WRITE, 0, REGISTER_DETECT, DETECT_SINGLE, CMD_TERM}; BYTE 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, 260, &bytes_received); // Check status . . . and ensure that cnt == 260 (number of range bins + 4) // The range bin data is now in response[3] thru response [258]. // response [0], [1] and [2] contain 0xEA and response[259] 0xFF (terminator).$

RaDeKL Radar API Programmer’s Guide 38 © Multispectral Solutions, Inc. 2006 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. Register Name Type Description FTDI USB Chip specific Please use these (except Serial Number and Device Description) only if you are familiar with the FTDI USB Chip interface. ft_handle void * Handle to the underlying USB device (do not use unless you are familiar with the FTDI USB chip API FTD2XX.h) ft_device_type ULONG USB device type (see FTD2XX.h for details) ft_serial_number char[16] Serial number (null-terminated) ft_description char[64] Device description (null-terminated) ft_device_id DWORD USB Chip device id (see FTD2XX.h for details) ft_product_id WORD USB Chip product id (see FTD2XX.h for details) ft_vendor_id WORD USB Chip vendor id (see FTD2XX.h for details) RaDeKL Radar specific Please use these values in your code instead of hard-coding them as configurations and ranges in future versions of the radar may change. resolution BYTE Resolution (currently RESOLUTION_1FOOT = 2) Use this value to determine the actual distance represented between successive range bin data samples. (See RaDeKLAPI.H for details) range_bins WORD The number of range bins available (currently 256) range_bin_min BYTE Minimum value of a range bin (currently 0) range_bin_max BYTE Maximum value of a range bin (currently 32) thresholds BYTE The number of Threshold registers (currently 32) threshold_min BYTE Minimum value of a Threshold register (currently 20) threshold_max BYTE Maximum value of a Threshold register (currently 227) tx_atten_min BYTE Minimum value for the Transmit Attenuation register (currently 0) tx_atten_max BYTE Maximum value for the Transmit Attenuation register (currently 63) rx_atten_min BYTE Minimum value for the Receive Attenuation register (currently 0) rx_atten_max BYTE Maximum value for the Receive Attenuation register (currently 255) interval_min BYTE Minimum value for the Interval register (currently 0) interval_max BYTE Maximum value for the Interval register (currently 4) Interval BYTE Current interval setting. Do not use this field! It is used for internal purposes and cannot be relied upon within the context of this API. version_id BYTE Full 8-bit version number of the RaDeKL Radar device version_id_minor 4 bits 4-bit Minor version number of the RaDeKL Radar device. This field overlays the low-order 4 bits of version_id. version_id_major 4 bits 4-bit Major version number of the RaDeKL Radar device. This field overlays the high-order 4 bits of version_id.

RaDeKL Radar API Programmer’s Guide 39 © Multispectral Solutions, Inc. 2006 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. Register Name Address Description REGISTER_ID_VERS 0 Version ID register REGISTER_DETECT 1 Detection command register REGISTER_TID_TIME 2 Interval for continuous detections REGISTER_RF_CONTROL 3 RF Control register REGISTER_TX_ATTEN 4 Transmitter attenuation register REGISTER_RX_ATTEN 5 Receiver attenuation register REGISTER_RANGE 6 RANGE register (shift by 512 range bins) REGISTER_DELAY 7 DELAY register (shift by 8 range bins) REGISTER_DAC1 8 DAC Threshold setting 1 REGISTER_DAC2 9 DAC Threshold setting 2 REGISTER_DAC3 10 DAC Threshold setting 3 REGISTER_DAC4 11 DAC Threshold setting 4 REGISTER_DAC5 12 DAC Threshold setting 5 REGISTER_DAC6 13 DAC Threshold setting 6 REGISTER_DAC7 14 DAC Threshold setting 7 REGISTER_DAC8 15 DAC Threshold setting 8 REGISTER_DAC9 16 DAC Threshold setting 9 REGISTER_DAC10 17 DAC Threshold setting 10 REGISTER_DAC11 18 DAC Threshold setting 11 REGISTER_DAC12 19 DAC Threshold setting 12 REGISTER_DAC13 20 DAC Threshold setting 13 REGISTER_DAC14 21 DAC Threshold setting 14 REGISTER_DAC15 22 DAC Threshold setting 15 REGISTER_DAC16 23 DAC Threshold setting 16 REGISTER_DAC17 24 DAC Threshold setting 17 REGISTER_DAC18 25 DAC Threshold setting 18 REGISTER_DAC19 26 DAC Threshold setting 19 REGISTER_DAC20 27 DAC Threshold setting 20 REGISTER_DAC21 28 DAC Threshold setting 21 REGISTER_DAC22 29 DAC Threshold setting 22 REGISTER_DAC23 30 DAC Threshold setting 23 REGISTER_DAC24 31 DAC Threshold setting 24 REGISTER_DAC25 32 DAC Threshold setting 25 REGISTER_DAC26 33 DAC Threshold setting 26 REGISTER_DAC27 34 DAC Threshold setting 27 REGISTER_DAC28 35 DAC Threshold setting 28 REGISTER_DAC29 36 DAC Threshold setting 29 REGISTER_DAC30 37 DAC Threshold setting 30 REGISTER_DAC31 38 DAC Threshold setting 31 REGISTER_DAC32 39 DAC Threshold setting 32

RaDeKL Radar API Programmer’s Guide 40 © Multispectral Solutions, Inc. 2006 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. The RaDeKL_DEVICEINFO structure returned by RaDeKL_GetDeviceInfo creates an appropriate union (overlay) to extract the major and minor version numbers. REGISTER_DETECT 1 Write-only register. Setting bit 0 (0x01) initiates single detect, setting bit 2 (0x04) initiates continuous detect. Clearing all bits (0x00) stops continuous detection. The other bits are for MSSI internal use only. REGISTER_TID_TIME 2 Interval for continuous detection. Values are 0 (1 second), 1 (500 ms), 2 (250 ms), 3 (100 ms) and 4 (50 ms). REGISTER_RF_CONTROL 3 Write-only register. Setting bit 0 (0x01) causes the radar device to be reset to factory settings. The other bits are for MSSI internal use only. REGISTER_TX_ATTEN 4 Sets the transmitter attenuation. Valid settings are in the range from 0 to 63 (decimal). For reference, a value of 63 causes 0 dB attenuation, 57 = -3 dB, 51 = -6 dB and 43 = -10 dB. See function definition of RaDeKL_SetTransmitAttenuation for more information. REGISTER_RX_ATTEN 5 Sets the receiver attenuation. Valid settings are in the range from 0 to 255 (decimal). For reference, a value of 0 causes 0 dB attenuation, 91 = -10 dB and 157 = -20 dB. See function definition of RaDeKL_SetReceiveAttenuation for more information. REGISTER_RANGE 6 Causes detection to be shifted by 512 range bin increments (256 feet at 0.5 foot resolution). REGISTER_DELAY 7 Causes detection to be shifted by 8 range bin increments (4 feet at 0.5 foot resolution). REGISTER_DAC1 thru REGISTER_DAC32 8 - 39 Contain the 32 DAC Threshold values.

RaDeKL Radar API Programmer’s Guide 41 © Multispectral Solutions, Inc. 2006 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. // //############################################################################## //############################################################################## // Include only ONCE #pragma once // Include Windows stuff #include <windows.h> #include <stdio.h> #include <math.h> #include <sys/timeb.h> // Include the FTDI USB Chip API header #include "FTD2XX.h" // // // Constant declarations // // // Max sizes for device serial number and description strings #define SIZE_SERIAL_NUMBER 16 #define SIZE_DESCRIPTION 64 // This string must occur somewhere within the device DESCRIPTION string #define RaDeKL_DESCRIPTION "RaDeKL WBT Radar B" // Status message codes (used in conjunction with the codes from FTD2XX.h) // --- FTDI specicific status codes #define RaDeKL_OK FT_OK // Currently 0 #define RaDeKL_INVALID_HANDLE FT_INVALID_HANDLE // Currently 1 #define RaDeKL_DEVICE_NOT_FOUND FT_DEVICE_NOT_FOUND // Currently 2 #define RaDeKL_DEVICE_NOT_OPENED FT_DEVICE_NOT_OPENED // Currently 3 #define RaDeKL_IO_ERROR FT_IO_ERROR // Currently 4 #define RaDeKL_INSUFFICIENT_RESOURCES FT_INSUFFICIENT_RESOURCES // Currently 5 #define RaDeKL_INVALID_PARAMETER FT_INVALID_PARAMETER // Currently 6 #define RaDeKL_INVALID_BAUD_RATE FT_INVALID_BAUD_RATE // Currently 7 #define RaDeKL_DEVICE_NOT_OPENED_FOR_ERASE FT_DEVICE_NOT_OPENED_FOR_ERASE // Currently 8 #define RaDeKL_DEVICE_NOT_OPENED_FOR_WRITE FT_DEVICE_NOT_OPENED_FOR_WRITE // Currently 9 #define RaDeKL_FAILED_TO_WRITE_DEVICE FT_FAILED_TO_WRITE_DEVICE // Currently 10 #define RaDeKL_EEPROM_READ_FAILED FT_EEPROM_READ_FAILED // Currently 11 #define RaDeKL_EEPROM_WRITE_FAILED FT_EEPROM_WRITE_FAILED // Currently 12 #define RaDeKL_EEPROM_ERASE_FAILED FT_EEPROM_ERASE_FAILED // Currently 13 #define RaDeKL_EEPROM_NOT_PRESENT FT_EEPROM_NOT_PRESENT // Currently 14 #define RaDeKL_EEPROM_NOT_PROGRAMMED FT_EEPROM_NOT_PROGRAMMED // Currently 15 #define RaDeKL_INVALID_ARGS FT_INVALID_ARGS // Currently 16 #define RaDeKL_NOT_SUPPORTED FT_NOT_SUPPORTED // Currently 17 #define RaDeKL_OTHER_ERROR FT_OTHER_ERROR // Currently 18 // --- RaDeKL API specific status codes #define RaDeKL_READ_TIMEOUT 201 #define RaDeKL_WRITE_TIMEOUT 202 #define RaDeKL_INCORRECT_SERIAL_NUMBER 203 #define RaDeKL_WRITE_REGISTER_FAILED 204 #define RaDeKL_READ_REGISTER_FAILED 205 #define RaDeKL_READ_DETECTION_FAILED 206

RaDeKL Radar API Programmer’s Guide 42 © Multispectral Solutions, Inc. 2006 #define RaDeKL_BAD_THRESHOLD 207 #define RaDeKL_BAD_TX_ATTEN 208 #define RaDeKL_BAD_RX_ATTEN 209 #define RaDeKL_BAD_RANGE_DELAY 210 #define RaDeKL_BAD_INTERVAL 211 #define RaDeKL_UNKNOWN_RESOLUTION 212 // Command codes #define CMD_READ 114 #define CMD_WRITE 119 #define CMD_TERM 255 #define CMD_DATA 234 // Detection register codes #define DETECT_SINGLE 1 #define DETECT_START_CONTINUOUS 4 #define DETECT_STOP_CONTINUOUS 0 // RF-Control register codes #define FIRMWARE_RESET 1 // Resolution setting constants #define RESOLUTION_UNKNOWN 0 #define RESOLUTION_6INCHES 1 #define RESOLUTION_1FOOT 2 // Continuous Collection Interval setting constants #define INTERVAL_1_SEC 0 #define INTERVAL_500_MS 1 #define INTERVAL_250_MS 2 #define INTERVAL_100_MS 3 #define INTERVAL_50_MS 4 // Version-Specific limits (see struct RaDeKL_DEVICEINFO below) #define V1_RESOLUTION RESOLUTION_1FOOT #define V1_RANGE_BINS 256 #define V1_RANGE_BIN_MIN 0 #define V1_RANGE_BIN_MAX 32 #define V1_THRESHOLDS 32 #define V1_THRESHOLD_MIN 20 #define V1_THRESHOLD_MAX 227 #define V1_TX_ATTEN_MIN 0 #define V1_TX_ATTEN_MAX 63 #define V1_RX_ATTEN_MIN 0 #define V1_RX_ATTEN_MAX 255 #define V1_INTERVAL_MIN 0 #define V1_INTERVAL_MAX 4 // RaDeKL Register addresses (16-bit) #define REGISTER_ID_VERS 0 // Version ID register #define REGISTER_DETECT 1 // Detection command register #define REGISTER_TID_TIME 2 // Interval for continuous detections (milliseconds) #define REGISTER_RF_CONTROL 3 // RF Control register #define REGISTER_TX_ATTEN 4 // Transmitter attenuation register #define REGISTER_RX_ATTEN 5 // Receiver attenuation register #define REGISTER_RANGE 6 // RANGE register (shift by 512 range bins) #define REGISTER_DELAY 7 // DELAY register (shift by 8 range bins) #define REGISTER_DAC1 8 // Threshold setting 1 #define REGISTER_DAC2 9 // Threshold setting 2 #define REGISTER_DAC3 10 // Threshold setting 3 #define REGISTER_DAC4 11 // Threshold setting 4 #define REGISTER_DAC5 12 // Threshold setting 5 #define REGISTER_DAC6 13 // Threshold setting 6 #define REGISTER_DAC7 14 // Threshold setting 7 #define REGISTER_DAC8 15 // Threshold setting 8 #define REGISTER_DAC9 16 // Threshold setting 9 #define REGISTER_DAC10 17 // Threshold setting 10 #define REGISTER_DAC11 18 // Threshold setting 11 #define REGISTER_DAC12 19 // Threshold setting 12 #define REGISTER_DAC13 20 // Threshold setting 13 #define REGISTER_DAC14 21 // Threshold setting 14 #define REGISTER_DAC15 22 // Threshold setting 15

$RaDeKL Radar API Programmer’s Guide 43 © Multispectral Solutions, Inc. 2006 #define REGISTER_DAC16 23 // Threshold setting 16 #define REGISTER_DAC17 24 // Threshold setting 17 #define REGISTER_DAC18 25 // Threshold setting 18 #define REGISTER_DAC19 26 // Threshold setting 19 #define REGISTER_DAC20 27 // Threshold setting 20 #define REGISTER_DAC21 28 // Threshold setting 21 #define REGISTER_DAC22 29 // Threshold setting 22 #define REGISTER_DAC23 30 // Threshold setting 23 #define REGISTER_DAC24 31 // Threshold setting 24 #define REGISTER_DAC25 32 // Threshold setting 25 #define REGISTER_DAC26 33 // Threshold setting 26 #define REGISTER_DAC27 34 // Threshold setting 27 #define REGISTER_DAC28 35 // Threshold setting 28 #define REGISTER_DAC29 36 // Threshold setting 29 #define REGISTER_DAC30 37 // Threshold setting 30 #define REGISTER_DAC31 38 // Threshold setting 31 #define REGISTER_DAC32 39 // Threshold setting 32 #define REGISTER_MAX 39 // MUST be same as the last valid register // // // Type definitions // // // Handle to RaDeKL Radar device typedef PVOID RaDeKL_HANDLE; // RaDeKL Radar device-specific info typedef struct RaDeKL_DEVICEINFO { // FTDI USB Chip specific data FT_HANDLE ft_handle; FT_DEVICE ft_device_type; char ft_serial_number[SIZE_SERIAL_NUMBER]; char ft_description[SIZE_DESCRIPTION]; union // This union allows us to overlay the 32-bit device_id { // with the 16-bit product_id and vendor_id DWORD ft_device_id; struct { WORD ft_product_id; // Low word WORD ft_vendor_id; // High word }; }; // RaDeKL Radar specific data BYTE resolution; // Currently always RESOLUTION_1FOOT WORD range_bins; // Currently always 256 BYTE range_bin_min; // Currently always 0 BYTE range_bin_max; // Currently always 32 BYTE thresholds; // Currently always 32 BYTE threshold_min; // Currently always 20 BYTE threshold_max; // Currently always 227 BYTE tx_atten_min; // Currently always 0 BYTE tx_atten_max; // Currently always 63 BYTE rx_atten_min; // Currently always 0 BYTE rx_atten_max; // Currently always 255 BYTE interval_min; // Currently always 0 BYTE interval_max; // Currently always 4 BYTE interval; // Current interval setting union // This union allows us to overlay the 8-bit version_id { // with the 4-bit major and 4-bit minor version_id BYTE version_id; struct { unsigned int version_id_minor:4; // Low nibble unsigned int version_id_major:4; // High nibble }; }; } RaDeKL_DEVICEINFO;$

Zebra Technologies RADEKL Radar Development Kit User Manual Programmers Guide

Zebra Technologies Corporation Radar Development Kit Programmers Guide

Contents

Programmers Guide

Navigation menu

Namespaces

Views

Navigation