Zebra Technologies RADEKL Operators Guide

MULTISPECTRAL SOLUTIONS, INC.

RaDeKL Radar API for Windows

Radar Developer’s Kit – Lite – Application Programming Interface

Programmer's Guide

Revised: 05 OCT 07

20300 Century Boulevard

Germantown, MD 20874-1132

Phone: (301) 528-1745

Fax: (301) 528-1749

Website: www.multispectral.com

Version 2.0

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 interfere nce 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

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

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 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. Instead, this interface provides a set of RaDeKL Radar specific functions to list available devices, open/close a specific radar device, set operational parameters and request single and continuous range detectio n data. Please refer to the enclosed folder “Code Example” for a complete and functional code example (in C) on how to list devices, open a device, set operational parameters, read range detection data and close the device.

USB Driver Installation

The RaDeKL Radar USB port is based on the FTDI FT2232C USB Chip, which requires a driver to operate.

Note: Do not download any updated drivers directly from the FTDI website! The RaDeKL Radar uses a custom PID (Product ID) in the USB definition and therefore requires a custom driver. Please use only the driver provided with RaDeKL Radar devices.

Before the RaDeKL Radar device can be used, the USB driver must be installed. This driver can only be installed if a RaDeKL Radar device is physically plugged into the USB port. Windows then detects the presence of a new USB device and uses its Plug & Play feature to aid in the installation of the driver.

Please follow these steps:

1. Ensure that you are running Windows 2000, Windows XP (or newer) on the target PC and that the PC has an available USB 2.0 (not 1.1 or 1.2) port. Have an A-B USB cable ready.

2. Extract the distribution ZIP file, containing the API and driver files. Note the location of the resulting folder. It should contain a sub-folder named “Driver”.

3. Connect the RaDeKL Radar device to the power supply and insert the power supply into a suitable electrical AC outlet (120 VAC).

4. Connect the RaDeKL Radar device to a free USB 2.0 port on your PC or laptop.

5. Windows should detect the new USB device and start the Found New Hardware Wizard.

6. Windows XP:

a. Click “No, not at this time” and then “Next”. b. Click “Install from a list or specific location” and then “Next”. c. Click “Search for the best driver in these locations” and “Include this location in the search”.

Click “Browse” and navigate to the folder noted in step 2 and then down to the “Driver” folder. Click “OK” and then “Next”.

d. Windows XP will find the correct MSSI IUO driver and display a warning about the driver

not having passed Windows Logo testing. Click “Continue Anyway”.

e. Windows will then detect a second USB device. Repeat the above steps for Windows XP to

complete installation.

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. 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 install ation, 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

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

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 continuou sly 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). 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 writeregister function (RaDeKL_SetXxxxx) will result in a read after write, which will interfere with an ongoing continuous detection, producing unpredictabl e 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

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) indica te 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 de scription.

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

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

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

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 descriptio n (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 descri ption lists and the associated character strings. If valid pointers are p assed 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 ra dar 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

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

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

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;

+ 33 hidden pages