Keynes Controls NetPod Developers Guide
NetPod Developers Guide
1.0 Introduction
1.1The following documentation is been created to aid software developers in the creation of applications utilizing the Keynes Controls NetPod instrumentation operating under the Microsoft Windows 32 bit operating systems. The documentation lists the functions calls which may be called upon by the developer to access, manipulate and control the functionality of the instrumentation.
1.2The NetPod instrumentation is controlled under the Microsoft operating systems by the Netpod.dll (Dynamic Link Library). It is calls made via the Netpod.dll that instructions are issued to the instruments. The Netpod.dll is the main interface used to units for access data from Ethernet networks.
1.3The following control operations are made available to the developer:
1)Starting and stopping data acquisition operations total system.
2)Starting and stopping data acquisition operations from individual units.
3)Querying driver status information.
4)Identifying the number of instruments and associated identification parameters connected to a network.
5)Examination of NetPod setup details. ADC type, serial numbers, channel gains etc.
6)Performing buffered or non-buffered read of analogue and digital data.
7)Setting the digital status lines.
8)Assigning digital input and output ports.
Features not currently supported are:
1)Changing instrument configurations during the acquisition of data.
2)Altering configurations by single function calls. (See section x.y for details).
1.4Information from the NetPod instrumentation is formed to packets prior to its transmission along a network. The packets are formed from a group of consecutive samples gathered from each of the channels within the instrument. For consistency with third party details on the network models the packets will be referred to as Datagrams.
2.0Operations
2.1The following section summaries the hardware operations within the instrument
2.2Hardware
2.2.1Upon being activated the NetPod instruments scan the network ports for traffic. This traffic can be from any instrument attached to the 10BaseT, 10Base2 or RS-485 networks or via requests for data from the serial port. On detecting data originating from one of the NetPod units assign the port from which traffic was detected to be the one that it will be using for communication to the outside world. The instruments scan initially for traffic from the LANs before looking for data originating on the serial ports. It is this way that the network port is assigned for use.
2.2.2It is not possible to mix 16 and 24 bit analogue cards within the same instrument. However, you can use 16 bit and 24 bit instruments on the same network. The format of the datagrams originating from the instruments is the same for both 16 bit and 24 bit data. You must ensure that ADC bit size is the same for all analogue cards installed in an instrument.
2.3Software
2.3.1The NetPod instrumentation and driver software has been designed to operate on local area industrial networks. Multiple instruments connected to several PCs and passing information to different applications packages simultaneously. Data can be passed from user to user in a transparent manner utilizing all the standard network operation. Data acquisition and control operations may be started, stopped and adjusted by each PC connected to the network.
2.3.1You should ensure that the Netpod.dll and PodMng.exe software packages are contained in the same directory before undertaking and development. The PodMng.exe program is responsible for creating the small task bar icon. The task bar icon can be used to directly start and stop acquisition operations and to activate the main configuration window.
2.3LAN Integration - 10Base2 & 10BaseT
2.3.1The Netpod driver interfaces directly to the Windows socket interface winsock.dll. The winsock.dll is a standard link library supplied by Microsoft for integrating TCP/IP to the Ethernet device driver.
2.3.2The Netpod.dll can be called multiple times (instances). It would be inefficient and wastefull of the processor resources if each call were to attempt to process that the TCP/IP packets. For this reason the Netpod.dll uses shared memory to allow each instance to access data from the instruments.
2.3.3It is important that only one instance is usedto processthe TCP/IP packets. It is recommended that this instance is taken by the PodMng program. All programs that use the DLL should call NP_SetState command with configuration parameter set to NP_RUNPODMNG. If the Pod Manager software is already running then the call will have no effect, however, should the Pod Manager software not be activated then this call will bring it to life and the default processing will be activated (such as scanning network).
2.4Network Control
2.4.1On driver activation, the system will by default scan the network using broadcast datagrams originating only from the NetPod instruments and searching for the existence of other PC's.
2.4.2A Windows registry command named SCANNET is provided to enable the software to scan a local area network for instruments, upon starting the software automatically i.e. when the PC boots.
2.4.3In order to determine how many units are present on a network, the user program must scan the network looking broadcast packets. The broadcast packets contain identification as well as process data. The identification data is used to indicate the NetPods available for use. During the scanning of the network, a window will appear and indicate that the system is looking for instruments. This action will take approximately 20 seconds and during this time no other operation is available through the Netpod.DLL. The user will have to wait for the NetPod table to become available. The NetPod table will contain details regarding each instrument detected on a chosen network.
2.4.4Unlike data acquisition cards installed directly into PCs work stations etc, the NetPod instruments may be removed, installed and reconfigured at any time.
2.4.5Any driver developer must be aware that a program may start on a network PC at any time and that data acquisition operations may already be underway. The developer should make use of the NP_GetStatus to test the status of operations before activating configuration and control function calls. It is possible to start and stop acquisition operations on different machines.
2.4.6Each NetPod has been assigned a unique address and can be configure just like any other piece of network equipment. The instruments support subnet addressing and respond to the ping network test.
3.0Operating Routines
3.1The following section details the procedures which have to be followed to configure and operate the NetPod instruments.
3.2Initialisation
The driver should ensure that there is a sockets callback instance. This can be done in one of two ways:
1. Calling NP_SetStatus(NP_SETCALLBACK), which will set the current thread to own the callback instance.
2. Calling NP_SetStatus(NP_RUNPODMNG), which will run the pod manager program, which will then own the callback instance
The second method is recommended procedure for initialisation procedure.
3.3Configuration
To change the configuration of a NetPod, the Config dialog box should be displayed. This is carried out by the DLL call
NP_SetState(NP_SHOWCFGDLG) . The config window will appear on the screen.
The user can then change the configuration using the dialog boxes provided. Currently the driver does not allow for the change of configuration by the user function calls. This feature will become available at a later date. Configuration changes can also not be made while the system is in run mode i.e. acquiring data..
(Must allow system config changes changes).
4.0DLL Function Calls
4.1The following section details the function calls available for use with the Netpod.DLL.
Function Calls
int NP_SimpleRead(int pid,int flag,void* results);
A procedure for reading the current analogue or digital state
Parameters
pid The pod identifier
flag One of NP_RAW, NP_CAL, NP_PROC, NP_DIGITAL, NP_TIME
results pointes to the buffer to be filled in the following format
NP_RAWarray of 16 32 bit integers
NP_CALarray of 16 single precision foating point
NP_PROCarray of 16 single precision foating point
NP_DIGITALsingle 32 bit integer
NP_TIMEsinge 64 bit integer (FILETIME format)
Return Value
Returns 1 if sucessfull, 0 if an error occured
Remarks
The procedure fills the results buffer with the latest analogue data from the NetPod dependant on the flags parameter
NP_RAWADC count of each channel.
NP_CALCalibrated data (in volts at ADC)
NP_PROCProcessed results (temperature etc.)
NP_DIGITALCurrent digital status
NP_TIMELatest time of acquisition
int NP_SetDigital(int pid,int value);
Sets the digital output state of a pod
Parameters
pidThe pod identifier
valueValue to set digital to
Return Value
Returns 1 if successful, 0 if an error occurred
Remarks
Sets the digital of the pod with pod identifier pid.
int NP_GetStatus(int stat); Gets driver system status
Parameters
stat Status parameter can be one of the following values
ValueMeaning
NP_ISCFGDLGSHOWNIs the configuration dialog shown
NP_ISRUNNINGIs the NetPod system running
NP_ISCALLBACKHas the main instance call back been installed
NP_ISINITSCANHas the system performed an initial scan of the network
Return Value
Returns 1 if true, 0 if false
Remarks
The driver should query NP_ISCALLBACK to determine whether the main call back instance has been installed, and NP_ISINITSCAN to determine if the pods have been identified
int NP_SetStatus(int stat);
Sets the driver system status
Parameters
stat Should be one of the following parameters
ValueMeaning
NP_STARTRUNStart the system acquisition
NP_STOPRUNStop the system acquisition
NP_TOGGLERUNToggle system acquisition state
NP_SETCALLBACKSet call back instance
NP_SHOWCFGDLG Show the configuration dialog window
NP_HIDECFGDLGHide the configuration dialog window
NP_RUNPODMNGRun the Pod Manager program
Return Value
Returns 1 if successful, 0 if an error occurred
Remarks
Drivers should use the NP_RUNPODMNG command to set the main call back instance rather than NP_SETCALLBACK.
int NP_GetPodInfo(int pid, TPodInfoStruct* Info);
Obtains general information about a particular pod
Parameters
pid The Pod identifier
Info Points to a TPodInfo structure, which is defined as follows
typedef struct _TPodInfoStruct
{
int PodId;
BYTE Ethernet[6];
TShortString StrEthernet;
int SWVersion;
TShortString PartNumber;
TShortString SerialNumber;
int ManYY,ManMM,ManDD;
TShortString StrManDate;
BYTE IPAddr[4];
TShortString StrIPAddr;
TShortString Name;
double SampleRate;
WORD DigDDR;
WORD DigDefault;
BYTE PortType[16];
} TPodInfoStruct;
Return Value
Returns 1 if successful, 0 if an error occurred
Remarks
int NP_GetChannelInfo(int pid, int cid, TChanneInfoStruct* Info);
Obtains general information from a specific channel
Parameters
pid The pod identifier
cid The channel number (0 to 15)
Info Pointer to a TChannelInfoStructure defined as follows:
typedef struct _TChanneInfoStruct
{
int PodID;
int Channel;
int IsInstalled;
int ADCType;
int ADCResolution;
int PortType;
int SWVersion;
TShortString PartNumber;
TShortString SerialNumber;
int ManYY,ManMM,ManDD;
TShortString StrManDate;
int Gain;
TShortString Name;
TShortString Units;
float DefCal[2];
float Cal[4];
} TChanneInfoStruct;
Return Value
Returns 1 if successful, 0 if an error occurred
Remarks
int NP_GetPodList(int* data);
Obtains a list of pod identifiers
Parameters
dataArray of 100 integers which will be filled with the identifiers of all the pods connected to the driver
Return Value
Returns 1 if successful, 0 if an error occurred
Remarks
NP_GetBufParam(int pid,TBufParamStruct* Param);
Obtains the Buffer Parameter status
Parameters
pidThe pod identifier
ParamPoints to a TBufParamStruct structure to be filled in, defined as follows:
typedef struct _TBufParamStruct
{
TSample StartSample;
TAccurateTime StartTime;
TSample LatestSample;
TAccurateTime LatestTime;
TSample LatestContSample;
TAccurateTime LatestContTime;
int reserved[64];
} TBufParamStruct;
Return Value
Returns 1 if sucessfull, 0 if an error occured
Remarks
Because aquisition is over a network, which is an unreliable medium, packets can get delayed or temperarily lost. The driver will attemp to re-request data from the NetPod, however, there may be a delay in this process. The LatestContSample and time parameters reflect that complete data has been aquired from the start to this point (unless it has timed out, in which case some of the data will contain null data)
int NP_TimeToSample(int pid, TAccurateTime time, TSample* samp);
Parameters
pidThe Pod identifier
timeThe time for which a sample is required
sampPointer to a TSample structure to recieve the sample for the requested time
Return Value
Returns 1 if successful, 0 if an error occurred
Remarks
NP_ChannelBufRead(int pid, int cid, int flag, TSample Start, int Len, float* results);
Performs a block read on a particular channel
Parameters
pidThe Pod identifier
cidThe channel number (0 to 15)
flagSee NP_SimpleRead for a discussion on flags
StartThe start sample
LenThe length of the buffer to be filled
resultsreturned results
Return Value
Returns 1 if successful, 0 if an error occurred
Remarks
1
Page No.