ACQ2XX_API
acq2xx_api.h
Go to the documentation of this file.
00001 /* ------------------------------------------------------------------------- */
00002 /* file acq2xx_api.h                                                         */
00003 /* ------------------------------------------------------------------------- */
00004 /*   Copyright (C) 2008 Peter Milne, D-TACQ Solutions Ltd
00005  *                      <Peter dot Milne at D hyphen TACQ dot com>
00006 
00007     This program is free software; you can redistribute it and/or modify
00008     it under the terms of Version 2 of the GNU General Public License
00009     as published by the Free Software Foundation;
00010 
00011     This program is distributed in the hope that it will be useful,
00012     but WITHOUT ANY WARRANTY; without even the implied warranty of
00013     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00014     GNU General Public License for more details.
00015 
00016     You should have received a copy of the GNU General Public License
00017     along with this program; if not, write to the Free Software
00018     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.                */
00019 /* ------------------------------------------------------------------------- */
00020 
00021 /** @file acq2xx_api.h ACQ2xx C++ API Definition. */
00022 
00023 /** @mainpage ACQ2XX C++ API Definition.
00024  *  @version $Revision: 1.11 $
00025  *  @author peter.milne@d-tacq.com
00026 
00027 - Aim:
00028   - provide a C++ control interface to D-TACQ ACQ2xx (ACQ216, ACQ196,ACQ132) 
00029   - the control interface is transport independent.
00030   - Applications interact with ACQ2xx card via instance of Acq2xx
00031   - The Transport is selected when the Acq2xx instance is created, and 
00032      may be ignored after that.
00033 - @see API Definition
00034  - Acq2xx  : ACQ2xx functional control class
00035  - Transport : Transport wrapper, hides connectivity details
00036 - @see Applications:
00037  - api_test.cpp
00038  - acqcmd.cpp
00039  - acq2sh.cpp
00040  - acqread.cpp
00041  - acq196_api_test.cpp : starts a continuous capture and monitors state, #samples
00042  - streamer.cpp : handles continuous streaming data, especially lock-in data
00043  - acq_demux.cpp : HOST-side channel demultiplexer.
00044 - @see Transport Implementations:
00045  - Dt100Transport.cpp
00046  - KddTransport.cpp
00047  - SoapTransport.cpp
00048  - SshTransport.cpp [feasible, but not implemented]
00049  */
00050 
00051 #ifndef __ACQ2XX_API_H__ 
00052 #define __ACQ2XX_API_H__ "$Revision: 1.11 $"
00053 
00054 
00055 #include "acq_api_common.h"
00056 
00057 class Frame;
00058 class Transport;
00059 
00060 
00061 /** process states. */
00062 enum STATE { 
00063         ST_STOP, 
00064         ST_ARM, 
00065         ST_RUN, 
00066         ST_TRIGGER, 
00067         ST_POSTPROCESS, 
00068         ST_CAPDONE 
00069 };
00070 /** input signal edge control. */
00071 enum acq2xx__EDGE { 
00072         EDGE_FALLING, EDGE_RISING 
00073 };
00074 /** input signal line select. */
00075 enum acq2xx__DIx { 
00076         DI_NONE, DI0, DI1, DI2, DI3, DI4, DI5 
00077 };
00078 /** output signal line select. */
00079 enum acq2xx__DOx { 
00080         DO_NONE, DO0, DO1, DO2, DO3, DO4, DO5 
00081 };
00082 
00083 enum acq2xx_Dx {
00084         D_NONE, D0, D1, D2, D3, D4, D5  
00085 };
00086 
00087 
00088 const char* toString(enum STATE s);
00089 
00090 /** capture modes. */
00091 enum acq2xx__MODE { 
00092         MODE_SOFT_TRANSIENT, 
00093         MODE_TRIGGERED_CONTINUOUS, 
00094         MODE_GATED_TRANSIENT,
00095         MODE_SOFT_CONTINUOUS
00096 };
00097 
00098 
00099 struct acq2xx_VRange {
00100         float vmin; float vmax;
00101 };
00102 
00103 
00104 
00105 struct acq2xx__Signal {
00106 /** aggregate holds full signal definition. */
00107         enum acq2xx__DIx dix;
00108         enum acq2xx__EDGE edge;
00109 };
00110 
00111 
00112 enum acq2xx_RoutePort {
00113 /** Route source or sink, sink may be OR of multiple values. */
00114         R_NONE,
00115         R_LEMO,
00116         R_FPGA,
00117         R_PXI,
00118         R_RIO
00119 };
00120 
00121 
00122 /** Acq2xx class wraps all ACQ2xx functionality.
00123  *  Acq2xx uses a Transport instance to take care of communications,
00124  *  so the same Acq2xx class works with any Transport.
00125  */
00126 class Acq2xx {
00127 
00128 protected:              
00129         Transport *transport;
00130         acq2xx_VRange *ranges;
00131         int ai, ao;
00132 
00133 public:
00134         Acq2xx(Transport* transport);
00135         /**< Create a transport independent ACQ protocol object. */
00136         virtual ~Acq2xx()
00137         {}
00138 
00139 
00140         Transport* getTransport(){
00141                 return transport;
00142         }
00143         STATUS setRoute(
00144                 enum acq2xx_Dx dx,
00145                 enum acq2xx_RoutePort in,
00146                 enum acq2xx_RoutePort out,
00147                 enum acq2xx_RoutePort out2 = R_NONE,
00148                 enum acq2xx_RoutePort out3 = R_NONE);
00149         /**< make a signal routing (connection). 
00150          * "signal" is a digital control signal
00151          * @param dx - the signal
00152          * @param in - source: input port (one only)
00153          * @param out - sink: output port (up to 3).
00154         */
00155 
00156         STATUS setExternalClock(
00157                 enum acq2xx__DIx dix,
00158                 int div = 1,
00159                 enum acq2xx__DOx dox = DO_NONE);
00160         /**< set External Clock definition.
00161          * @param dix - the signal
00162          * @param div - integer divide of dix
00163          * @param dox - optional output for divided signal
00164          */ 
00165         STATUS setInternalClock(
00166                 int hz,
00167                 enum acq2xx__DOx dox = DO_NONE);
00168         /**< set Internal Clock defiition.
00169          * @param hz - frequency in Hz
00170          * @param dox - output the clock on this line
00171          */
00172 
00173         STATUS getInternalClock(int& hz);
00174         /**< get the actual Internal Clock frequency.
00175          * @param hz - output value
00176          */
00177 
00178         STATUS getAvailableChannels(int& maxChannels);
00179         /**< get the number of channels on the card.
00180          * @param maxChannels - output available channels.
00181          */
00182 
00183         STATUS selectChannels(const char* channelMask);
00184         /**< set the active channel mask.
00185          *   NB not all masks are valid, hardware will select nearest mask
00186          *   that includes all channels.
00187          * @param channelMask - mask selects active channels 1=> enabled
00188          */
00189 
00190         STATUS getSelectedChannels(char * channelMask, int *count);
00191         /**< get the actual effective channel mask.
00192          * @param channelMask - outputs the actual mask
00193          * @param count - outputs selected channel count
00194          */
00195 
00196         STATUS getChannelRanges(acq2xx_VRange * ranges, int maxRanges); 
00197         /**< get a list of calibrated range values for each channel.
00198          * @param ranges - user allocated buffer to hold values.
00199          *      index from 1
00200          * @param maxRanges - length of user buffer
00201          */
00202 
00203         STATUS setPrePostMode(
00204                 int prelen, int postlen,
00205                 enum acq2xx__DIx dix = DI3,
00206                 enum acq2xx__EDGE edge = EDGE_FALLING);
00207         /**< configure the capture Mode.
00208          * @param prelen - number of samples before trigger
00209          * @param postlen - number of samples after trigger
00210          * @param dix - signal line for trigger
00211          * @param edge - sense of the signal
00212          */
00213 
00214         STATUS setTriggeredPostMode(int postlen) {
00215                 return setPrePostMode(0, postlen);
00216         }       
00217         /**< configure a capture with POST samples only and a hard trigger
00218          * @param postlen - number of samples after trigger
00219          */
00220 
00221         STATUS setSoftTriggeredMode(int postlen) {
00222                 return setPrePostMode(0, postlen, DI_NONE);
00223         }
00224         /**< configure a capture with SOFT TRIGGER.
00225          * @param postlen - number of samples to capture
00226          */
00227 
00228         STATUS setArm();
00229         /**< arm the card to start the capture. */
00230         STATUS setAbort();
00231         /**< abort a capture */
00232         STATUS getState(enum STATE& state);
00233         /**< output card state.
00234          * @param state - output state value.   
00235          */
00236         
00237         STATUS waitState(enum STATE state, int timeout = 10000);
00238         /**< wait for selected State to occur, or timeout
00239          * @param state - state to wait for
00240          * @param timeout - timeout in msec
00241          */
00242 
00243         STATUS getNumSamples(int* total, 
00244                 int* pre = 0, int* post = 0, int *elapsed = 0);
00245         /**< query current capture state.
00246          * @param total - output total samples
00247          * @param pre - output pre trigger samples
00248          * @param post - output post- trigger samples
00249          * @param elapsed - output samples since arm
00250          * NB: any param can be null, and is then ignored
00251          */
00252                 
00253         STATUS readChannel(int channel, short* data,
00254                            int nsamples, int start = 0, int stride = 1);
00255         /**< read and output raw data for channel
00256          * @param channel - channel number 1..N
00257          * @param data - caller's buffer
00258          * @param nsamples - max samples to read
00259          * @param start - start sample in data set
00260          * @param stride - stride [subsample] value
00261          * @returns actual samples returned or STATUS_ERR
00262          */
00263 
00264         STATUS readChannelVolts(int channel, float* data_volts,
00265                            int nsamples, int start = 0, int stride = 1);
00266         /**< read and output calibrated data for channel
00267          * @param channel - channel number 1..N
00268          * @param data_volts - caller's buffer
00269          * @param nsamples - max samples to read
00270          * @param start - start sample in data set
00271          * @param stride - stride [subsample] value
00272          * @returns actual samples returned or STATUS_ERR
00273          */
00274 
00275         STATUS readStreamingFrame(Frame* frame, unsigned id);
00276         /**< For streaming data, read the frame
00277          * @param frame - caller buffer to fill with data
00278          * @param id - previous frame # - id=0 means "start streaming"
00279          * @returns STATUS_OK or STATUS_ERR
00280          */
00281         STATUS stopStreaming(void);
00282         /**< stops and clears up a previous streaming connection
00283          * @returns STATUS_OK or STATUS_ERR
00284          */
00285 };
00286 
00287 
00288 #endif //__ACQ2XX_API_H__