VDATS_Wrapper_Style_Guide.pdf

VDATS Wrapper Style Guide Rev000

WRAPPER STYLE GUIDE

FOR THE

VERSATILE DEPOT AUTOMATIC TEST

STATION (VDATS)

Prepared by:

st Software Maintenance Squadron

402d Software Maintenance Group

402d Maintenance Wing

Warner Robins Air Logistics Center

Revision History

Revision Changes Date

000 Initial Release 30 November 2009 ii

TABLE OF CONTENTS

1. Scope

2. Introduction

3. Related Documents

4. Wrapper Development

4.1. Integration Development Environment

4.2. Build Options

4.3. Wrapper Structure

5. Header File

5.1. Distribution Statement

5.2. Instrument Information

5.3. Revision History

5.4. #ifndef Statements

5.5. Include Statements

5.6. Type Definitions

5.7. Enumerations

5.8. Functions

5.8.1. Required Functions

5.8.2. Prototypes

5.9. Header Example

6. Source File

6.1. Function Definitions

6.2. Error Handling

6.3. User Interaction

6.4. Instrument Specific Programming

1. Scope

This document is the Wrapper Style Guide for the Versatile Depot Automated Test Station

(VDATS). This style guide applies to all wrappers developed for the VDATS.

2. Introduction

A wrapper is layer of software comprised of a set of generic functions for a class of instrumentation that enables the developer to write test programs without direct communication to a specific instrument.

The goal of the wrapper is to prevent the dependence of test programs on test station hardware.

This increased flexibility allows any test station instrument to be substituted with a functional replacement with little to no effect on existing test programs. The wrapper layer should be modified in a way that makes the hardware transition seamless for test program operation and maintenance.

Other goals of the wrapper include reducing the complexity of instrumentation programming, promoting test program code reuse and consistency, and maintaining test program development tool independence.

The purpose of this style guide is to provide a general guide for the structure and design of all

VDATS wrappers. This style guide provides minimum requirements that all wrappers will follow and example code for a wrapper.

3. Related Documents

Document Number Description

TO 51C3-1-144-3

TO 51C3-1-143-3

283-001-WRAPPERCOMMON-SRS

VDATS Digital Analog Operation and Maintenance

Instructions with IPB

VDATS Radio Frequency Operation and

Maintenance Instructions with IPB

Wrapper Common Software Requirements

Specification

4. Wrapper Development

4.1. Integration Development Environment

VDATS Wrappers shall be developed in the version of National Instruments LabWindows/CVI installed on the VDATS System Image, as specified in TO 51C3-1-144-3.

4.2. Build Options

VDATS Wrappers shall be built into release mode dynamic link library.

4.3. Wrapper Structure

VDATS Wrappers shall be comprised of the following components:

1. Header File (.h)

2. Source File (.c)

3. Dynamic Link Library (.dll)

4. Library (.lib)

5. Header File

Each instrument wrapper should have a single header file (.h) that contains the following:

1. Distribution statement

2. Instrument information

3. Revision history

4. #ifndef statement

5. Include statements (#include)

6. Preprocessor macros (#define)

7. Type definitions

8. Enumerations

9. Function prototypes

5.1. Distribution Statement

This is the first item in the header file and it should contain any legal information pertaining to the distribution and use of the header file. This statement should be plain text in a C-style block comment.

Example:

UNCLASSIFIED

DISCLOSURE NOTICE - This information is furnished upon the condition that it will not be released to another nation without the specific authority of the

Department of the Air Force of the United States, that it will be used for military purposes only, that individual or corporate rights originating in the information, whether patented or not, will be respected, that the recipient will report promptly to the United States, any known or suspected compromise, and that the information will be provided substantially the same degree of security afforded it by the Department of Defense of the United

States. Also, regardless of any other markings on the document, it will not be downgraded or declassified without written approval of the originating

United States agency.

DISTRIBUTION STATEMENT D. Distribution authorized to the Department of

Defense and U.S. DoD contractors only (Critical Technology) (21 Nov 2008).

Other requests shall be referred to 565 CBSS/GBLB.

WARNING - This document contains technical data whose export is restricted by the Arms Export Control Act (Title 22, U.S.C., Sec 2751 et seq.) or the

Export Administration Act of 1979, as amended, Title 50, U.S.C., App. 2401 et seq. Violations of these export laws are subject to severe criminal penalties. Disseminate in accordance with provisions of DoD Directive

5230.25.

HANDLING AND DESTRUCTION NOTICE - Comply with distribution statement and destroy by any method that will prevent disclosure of contents or reconstruction of the document.

5.2. Instrument Information

This block should contain the generic name of the instrument (i.e. Digital Multimeter), the reference designator for the instrument (i.e. DMM), and optionally a brief description of the instrument. This information should be in a C-style block comment.

Example:

File: cvi_abc.h

Device: Automatic Bean Counter (ABC)

This instrument counts beans automatically.

5.3. Revision History

This block should contain the entire revision history of the wrapper. Each entry should contain the date, name of person making the change, and a short comment describing the change.

Example:

Revision Name Comments

2009.01.01 Milligan, D Initial release

2009.02.15 Sheppard, S Fixed bean sync problem

2009.03.15 Espinosa, C Added ABC_TriggerOnBean function

5.4. #ifndef Statements

This is the first item of actual C code. This statement is a C Preprocessor macro that prevents this header file from being included more than once. This macro consists of 3 separate lines of code. The first two lines should be the first lines of actual code in the file and appear after the revision history (xxx is the reference designator of the instrument):

#ifndef _cvi_xxx_h

#define _cvi_xxx_h

The third should be the very last line in the file, appearing after the last function prototype:

#endif

Example:

#ifndef _cvi_abc_h

#define _cvi_abc_h

... the rest of the header file contents ...

#endif

5.5. Include Statements

Any files that need to be included for the proper compilation of this file should go here.

Example:

#include <visa.h>

5.6. Type Definitions

Any custom type definitions should go here. This section is optional.

Example:

typedef struct int count;

double number;

char* name;

MyStruct;

5.7. Enumerations

Any definitions for enumerated types should go here. Each enumeration should have a C style block comment directly preceding that describes the enumeration and its use. This section is optional.

Example:

typedef enum

ABC_BEAN_BLACK = 0,

ABC_BEAN_RED = 1,

ABC_BEAN_PINTO = 2

ABC_BEAN;

5.8. Functions

5.8.1. Required Functions

There are six basic functions required by each wrapper in addition to the functions specific to the type of instrument.

1. XXX_GetHandle – cache the ViSession handle for the test program

2. XXX_GetName – returns an ASCII string of the name of the device

3. XXX_GetWrapperVersion – returns an ASCII string of the version number of the installed wrapper

4. XXX_Online – communicates with the instrument to determine online status

5. XXX_Reset – returns the instrument to the reset state

6. XXX_Self-Test – runs the instrument internal self-test

5.8.2. Prototypes

The header file should contain a function prototype for each function of the wrapper. Group similar functions together and put a comment block before those functions. Provide a name and description of the group, and optionally code examples for the group in this comment.

Every function name should begin with the reference designator for the instrument followed by an underscore “_” then rest of the function name. Use medial capitals (i.e. “the function name” =

“TheFunctionName”) for multi-word function names.

Each function should list input and output parameters with the data type, parameter name, and a description of the parameter as a comment.

Example:

Bean Setup Routines

- ABC_GetBeanWaveform

- ABC_SetMode

- ABC_TriggerOnBean

Functions to setup the ABC for bean counting

ABC_GetBeanWaveform

-Measures the waveform of a time varying bean field

Example:

double wavedata[1024];

ABC_GetBeanWaveform(1,wavedata,1024);

Inputs:

int channel [1|2] the channel to use int maxSize The max number of data points to read

Outputs:

double[] waveform Array of values containing the measured waveform

Returns:

void void ABC_GetBeanWaveform(int channel,double waveform[],int maxSize);

5.9. Header Example

UNCLASSIFIED

DISCLOSURE NOTICE - This information is furnished upon the condition that it will not be released to another nation without the specific authority of the

Department of the Air Force of the United States, that it will be used for military purposes only, that individual or corporate rights originating in the information, whether patented or not, will be respected, that the recipient will report promptly to the United States, any known or suspected compromise, and that the information will be provided substantially the same degree of security afforded it by the Department of Defense of the United

States. Also, regardless of any other markings on the document, it will not be downgraded or declassified without written approval of the originating

United States agency.

DISTRIBUTION STATEMENT D. Distribution authorized to the Department of

Defense and U.S. DoD contractors only (Critical Technology) (21 Nov 2008).

Other requests shall be referred to 565 CBSS/GBLB.

WARNING - This document contains technical data whose export is restricted by the Arms Export Control Act (Title 22, U.S.C., Sec 2751 et seq.) or the

Export Administration Act of 1979, as amended, Title 50, U.S.C., App. 2401 et seq. Violations of these export laws are subject to severe criminal penalties. Disseminate in accordance with provisions of DoD Directive

5230.25.

HANDLING AND DESTRUCTION NOTICE - Comply with distribution statement and destroy by any method that will prevent disclosure of contents or reconstruction of the document.

File: cvi_abc.h

Device: Automatic Bean Counter (ABC)

This instrument counts beans automatically

Revision Name Comments

2009.01.01 Milligan, D Initial release

2009.02.15 Sheppard, S Fixed bean sync problem

2009.03.15 Espinosa, C Added ABC_TriggerOnBean function

#ifndef _cvi_abc_h

#define _cvi_abc_h

#include <visa.h>

/* BEAN Macro */

#define BEAN "BEAN"

Enumeration representing types of beans typedef enum

ABC_BEAN_BLACK = 0,

ABC_BEAN_RED = 1,

ABC_BEAN_PINTO = 2

ABC_BEAN;

Modes for the bean counter typedef enum

ABC_BEAN_MODE_AUTO = 0,

ABC_BEAN_MODE_INT = 1,

ABC_BEAN_MODE_EXT = 2

ABC_BEAN_MODE;

General Purpose Routines

- ABC_GetHandle

- ABC_GetName

- ABC_GetWrapperVersion

- ABC_Online

- ABC_Reset

- ABC_Self-Test

General purpose functions that are common to all instruments

ABC_GetHandle

- Returns the ViSession handle for the instrument;

None

ViSession

ViSession ABC_GetHandle(void);

ABC_GetName

- Returns an ASCII string of the name of the device char* DeviceName void ABC_GetName(char* DeviceName);

ABC_GetWrapperVersion

- Return an ASCII string of the version number of the wrapper char* Version void ABC_GetWrapperVersion(char* Version);

ABC_Online

- Communicates with instrument to determine online status int int ABC_Online(void);

ABC_Reset

- Returns the instrument to the reset state;

int int ABC_Reset(void);

Bean Setup Routines

- ABC_SetMode

- ABC_TriggerOnBean

Functions to setup the ABC for bean counting

ABC_SetMode

- Sets the bean counting mode

ABC_BEAN_MODE mode The counting mode void ABC_SetMode(ABC_BEAN_MODE mode);

ABC_TriggerOnBean

- Sets up the instrument to trigger on a type of bean

ABC_BEAN bean The type of bean to trigger on void ABC_TriggerOnBean(ABC_BEAN bean);

Bean Data Aquisition Routines

- ABC_CountBeans

- ABC_GetBeanWaveform

Measurement functions

ABC_CountBeans

- Counts the beans int ABC_CountBeans(int channel);

ABC_GetBeanWaveform

-Measures the waveform of a time varying bean field

Example:

double wavedata[1024];

ABC_GetBeanWaveform(1,wavedata,1024);

int maxSize The max number of data points to read double[] waveform Array of values containing the measured waveform void ABC_GetBeanWaveform(int channel,double waveform[],int maxSize);

#endif

6. Source File

Each instrument wrapper should have a single source file (.c) that contains the function definitions for the function prototypes declared in the header file.

6.1. Function Definitions

Each function declared in the header file must be defined in the source file. The wrapper functions should be coded in a way that the test program developer is not required to know instrument specific information such as instrument handle, instrument address, bus information, VISA resource identification, etc.

Example:

ViSession ABC_GetHandle(void) { static ViSession Handle = NULL;

char message[255],ErrorMsg[255];

int status;

if (Handle != NULL) return Handle;

status = NgBeanCounter_init ("ABC", VI_FALSE, VI_FALSE, &Handle);

if (status != VI_SUCCESS) {

NgBeanCounter _error_message (Handle, status, message);

sprintf(ErrorMsg,"ABC Error: %d , %s\n", status, message);

InstrumentError(ErrorMsg);

Handle = NULL;

return Handle;

6.2. Error Handling

Each function in the source file should handle any errors occurred at runtime. After each function call to the instrument, the wrapper must check the status of the instrument. If the status is an error condition, the wrapper must capture the error code and retrieve an instrument error message, if available. The function would then pass the error message into the InstrumentError function that is defined in the wrappercommon function set. The requirements for the

InstrumentError function can be found in the Wrapper Common Software Requirements

Specification.

Example:

void ABC_CheckStatus(ViSession session,ViStatus status) {

ViChar errorMessage[512] = "ABC error: ";

char errorDesc[512];

if (status != VI_SUCCESS) {

NgBeanCounter _error_message (NULL, status, errorDesc);

strcat(errorMessage,errorDesc);

InstrumentError(errorMessage);

6.3. User Interaction

There should be no functions that interact with the test program operator. This includes printf statements or any other console input/output functions. All user interaction must be done at the test program level and excluded from the wrapper.

6.4. Instrument Specific Programming

VDATS Wrappers should avoid implementing functionality or code that is unique to one particular instrument model or manufacturer. The wrapper should be developed in a way that the software can be modified to account for future hardware changes.