Sifos Technologies PowerSync PDA-300 Reference Manual
PDA-300 API Library Reference Manual
1
Sifos Technologies
PowerSync Device Analyzer
PDA-300
API Library Reference
Manual
Version 3.3
Revised October 4, 2012
Copyright © 2012 Sifos Technologies
October 4, 2012 Sifos Technologies page
PDA-300 API Library Reference Manual
2
Sifos Technologies, Inc.
(978) 640-4900 Phone
(978) 640-4990 FAX
Disclaimer
The information contained in this manual is the property of Sifos Technologies, Inc., and is furnished for use by
recipient only for the purpose stated in the Software License Agreement accompanying the user documentation. Except
as permitted by such License Agreement, no part of this publication may be reproduced, stored in a retrieval system, or
transmitted, in any form or by any means, without the prior written permission of Sifos Technologies, Inc.
Information contained in the user documentation is subject to change without notice and does not represent a
commitment on the part of Sifos Technologies, Inc. Sifos Technologies, Inc. assumes no responsibility or liability for
any errors or inaccuracies that may appear in the user documentation.
October 4, 2012 Sifos Technologies page
PDA-300 API Library Reference Manual
3
Table of Contents
1. Introduction..................................................................................................................................... 5
1.1. PDA-300 API Library Introduction ................................................................................................................................ 5
1.2. System Requirements .................................................................................................................................................. 5
1.3. Installation ..................................................................................................................................................................... 6
1.4. Reference Manual Organization ................................................................................................................................... 6
2. PDA-300 API Function Definitions ................................................................................................ 7
2.1. Calling Convention ....................................................................................................................................................... 7
2.2. Error Handling ............................................................................................................................................................... 8
2.3. Enumerations ................................................................................................................................................................ 9
2.4. Functions .................................................................................................................................................................... 10
2.4.1. pda300_Connect................................................................................................................................................... 10
2.4.2. pda300_Disconnect ................................ ................................................................................................ .............. 11
2.4.3. pda300_GetVersion ............................................................................................................................................. 11
2.4.4. pda300_GetHardwareVer .................................................................................................................................... 11
2.4.5. pda300_SetAlt ...................................................................................................................................................... 12
2.4.6. pda300_GetAlt ..................................................................................................................................................... 12
2.4.7. pda300_SetMdi .................................................................................................................................................... 13
2.4.8. pda300_GetMdi ................................................................................................................................................... 13
2.4.9. pda300_SetEvents ................................................................................................................................................ 14
2.4.10. pda300_GetEvents ............................................................................................................................................... 14
2.4.11. pda300_SetVportLevel ........................................................................................................................................ 15
2.4.12. pda300_GetVportLevel ........................................................................................................................................ 15
2.4.13. pda300_MeasRdet ................................................................................................................................................ 16
2.4.14. pda300_MeasCdet ................................................................................................................................................ 17
2.4.15. pda300_MeasClass ............................................................................................................................................... 18
2.4.16. pda300_SetVportState.......................................................................................................................................... 19
2.4.17. pda300_GetVportState ......................................................................................................................................... 19
2.4.18. pda300_AdjustVportLevel ................................................................................................................................... 20
2.4.19. pda300_MeasPowerDraw .................................................................................................................................... 21
2.4.20. pda300_StartTraceCapture ................................................................................................................................... 22
2.4.21. pda300_StopTraceCapture ................................................................................................................................... 23
2.4.22. pda300_Run802dot3ATtest ................................................................................................................................. 24
2.4.23. pda300_GetErrMessage ....................................................................................................................................... 25
2.4.24. pda300_SetDebugPath ......................................................................................................................................... 26
2.4.25. pda300_DebugFileWrite ...................................................................................................................................... 27
2.4.26. pda300_SetTimeouts ............................................................................................................................................ 27
3. PDA-300 API Library Definitions for Other Languages ............................................................ 28
3.1. Visual Basic 6 .............................................................................................................................................................. 28
3.1.1. Type Differences .................................................................................................................................................. 28
3.1.2. Enumerations ....................................................................................................................................................... 28
3.1.3. Service Functions ................................................................................................................................................. 28
3.1.4. VB6 Compatible Declarations ............................................................................................................................. 28
3.2. Visual Basic .NET........................................................................................................................................................ 30
3.2.1. Type Differences .................................................................................................................................................. 30
3.2.2. Enumerations ....................................................................................................................................................... 30
3.2.3. Service Functions ................................................................................................................................................. 30
3.2.4. VB .NET Compatible Declarations ...................................................................................................................... 30
3.3. LabView ....................................................................................................................................................................... 31
October 4, 2012 Sifos Technologies page
PDA-300 API Library Reference Manual
4
3.3.1. Type Differences .................................................................................................................................................. 31
3.3.2. Enumerations ....................................................................................................................................................... 31
3.3.3. LabView VIs ................................................................................................................................ ........................ 31
4. PDA-300 API Example Code ........................................................................................................ 32
4.1. C Code Example ......................................................................................................................................................... 32
4.2. Visual Basic 6 Code Example .................................................................................................................................... 39
4.3. Visual Basic .NET Code Example .............................................................................................................................. 40
4.4. LabView Code Example .............................................................................................................................................. 46
October 4, 2012 Sifos Technologies page
PDA-300 API Library Reference Manual
5
1. Introduction
1.1. PDA-300 API Library Introduction
The Sifos Technologies PDA-300 Powered Device Analyzer is a test instrument designed to 1) assure interoperability
of a Powered Device (PD) under the IEEE 802.3at standard, and 2) build confidence that PD’s are properly specified
for purposes of classification and mutual identification with PSE’s.
The PDA-300 can operate either as a stand-alone instrument or under control of PC hosted software. Please refer to the
PDA-300 Technical Reference Manual for detailed information regarding the operation of the instrument and its test
capabilities.
This document describes an Application Programming Interface (API) library that allows the instrument to be remotely
controlled from a PC over an RS-232 serial connection. This API library is published as a Dynamic Link Library (DLL)
for use on Microsoft Windows platforms.
On a Windows platform, any language capable of calling Win32 API functions should be able to use the PDA-300 API
library.
The PDA-300 remote control capability effectively provides the means for the front panel softkeys to be ‘pressed’
programmatically via the serial interface. Front panel softkeys cause the instrument to modify configuration settings,
change menu contexts, apply power to a PD, and perform measurements. After a softkey is programmatically selected,
the related menu context specific text is output by the instrument via the serial interface. The API library completely
encapsulates these menu operations, cycling through the correct menus in the required order to provide a caller with the
capability to defining the instrument settings, to enable and disable Vport, and to perform specific measurements by
calling functions specific to each of those actions.
For efficiency, the functions in the API library are partitioned to provide the caller with the means of establishing the
desired settings (ALT, Polarity, number of Classification Events, and Vport level) before traversing the menus required
to modify these settings in the instrument. If the ALT, Polarity, and number of Classification Events settings are not
changed, the instrument can remain in a single menu context that allows Vport to turned on and off, the voltage level
output to be adjusted, and also allows all of the measurements to be performed. If any one of the ALT, Polarity, and
number of Classification Events settings are altered, the instrument will have to be cycled back through the relevant
menus to modify these settings. The API library will choose the appropriate action any time a function that is
dependent on the configuration settings is called. These functions are the ones that perform measurements, and the one
that allows Vport to be turned on.
1.2. System Requirements
For Microsoft Windows
Windows 2000 SP3 or later, through Windows 7
A serial port capable of supporting 9600 baud, 8 bit, no parity, 1 stop bit.
October 4, 2012 Sifos Technologies page
PDA-300 API Library Reference Manual
6
1.3. Installation
The DLL and related files are furnished on the Sifos PDA-300 CD-ROM, located under the directory \API_files.
The API library binary file must be placed in a location that the application program you are using can find at runtime.
For Windows platforms, there are specific rules that the operating system uses to locate a DLL:
1. searches under the current working directory
2. searches under C:\Windows
3. searches under C:\Windows\System32
4. searches under directories defined in the PATH environment variable
The .h, .lib, and .bas files should be placed wherever necessary to access them from your application development
environment. NOTE: the .lib file was produced with a Microsoft C version 6 linker.
1.4. Reference Manual Organization
Section 2 of this manual contains the PDA-300 API function definitions, and related enumeration type definitions for
any language able to call a standard C function.
Section 3 of this manual contains information related to using the PDA-300 API with different languages.
Section 4 of this manual contains example code showing how to call functions in the PDA-300 API library.
October 4, 2012 Sifos Technologies page
PDA-300 API Library Reference Manual
7
pda300_SetAlt
pda300_GetAlt
pda300_SetMdi
pda300_GetMdi
pda300_SetEvents
pda300_GetEvents
pda300_SetVportLevel
pda300_GetVportLevel
pda300_MeasRdet
pda300_MeasCdet
pda300_MeasClass
pda300_SetVportState
pda300_GetVportState
pda300_MeasPowerDraw
pda300_AdjustVportLevel
pda300_StartTraceCapture
2. PDA-300 API Function Definitions
The PDA-300 API function prototypes and associated enumerations are defined in the file pda300API.h.
As described above, the functions in the API library are partitioned to insure the efficiency in the number of menu
traversals required. The function listed in Table 1, Library Settings Only Functions provide the caller with the means of
establishing the desired settings (ALT, Polarity, number of Classification Events, and Vport level) before traversing the
menus required to modify these settings in the instrument. Note: these functions do not perform any I/O with the
instrument – the values that they communicate to the API library are stored in local memory, and will be used to
configure the instrument settings when one of the functions listed in Table 2 Instrument Operation Functions is called.
Table 1
Library Settings Only Functions
Table 2
Instrument Operation Functions
2.1. Calling Convention
On Microsoft Windows platforms, the calling convention required to call the API functions is __stdcall.
October 4, 2012 Sifos Technologies page
PDA-300 API Library Reference Manual
8
Integer Value
#define Name
0
PDA300_NO_ERROR
1
PDA300_SERIAL_COMM_ERROR
2
PDA300_INVALID_FW_VERSION
3
PDA300_INVALID_PARAMETER_VALUE
4
PDA300_INVALID_ICLASS
5
PDA300_NULL_POINTER
6
PDA300_FILE_ERROR
7
PDA300_MENU_ERROR
8
PDA300_NOT_IN_LM_MENU
9
PDA300_FAST_SAMPLE_RUNNING
10
PDA300_FAST_SAMPLE_NOT_RUNNING
11
PDA300_TRACE_ERROR
12
PDA300_VPORT_NOT_ENABLED
13
PDA300_TRACE_FILE_FORMAT_ERROR
14
PDA300_TEST_NEVER_COMPLETED
2.2. Error Handling
Each of the PDA-300 API functions returns a status value. The various status values are listed in Table 3 Function
Return Values.
Table 3
Function Return Values
A user developed application program should always test the status returned by an API function.
When an API function returns a status other than PDA300_NO_ERROR, the calling application can call the API
function pda300_GetErrMessage to retrieve a message string associated with that error.
October 4, 2012 Sifos Technologies page
PDA-300 API Library Reference Manual
9
2.3. Enumerations
enum _pda300AltSetting { ALT_A = 1, ALT_B = 2 };
typedef enum _pda300AltSetting pda300AltSetting;
enum _pda300MdiSetting { MDI = 1, MDIX = 2 };
typedef enum _pda300MdiSetting pda300MdiSetting;
enum _pda300ClassEvents { ONE_EVENT = 1, TWO_EVENTS = 2 };
typedef enum _pda300ClassEvents pda300ClassEvents;
enum _pda300VportState { VPORT_OFF = 0, VPORT_ON = 1 };
typedef enum _pda300VportState pda300VportState;
enum _pda300Quadrants { ONE_QUADRANT = 1, FOUR_QUADRANTS = 2 };
typedef enum _pda300Quadrants pda300Quadrants;
October 4, 2012 Sifos Technologies page
PDA-300 API Library Reference Manual
10
2.4. Functions
The more likely error return values are listed for each function. Other return values are possible – refer to Table 3 in the Error
Handling section of this document for all possible return values.
2.4.1. pda300_Connect
function: pda300_Connect
description: opens a handle to the defined COM port, and attempts to communicate with a PDA-300. If an instrument
responds, the firmware version is checked to verify that it will support this API library. If the instrument is compatible
with the API library, the front panel is locked out. The hardware version is read and stored, to support decisions related
to the sample rate (rates are specified in the PDA-300 Technical Reference Manual).
NOTE: if Vport is ON when this function is called, it will be turned off as the connection is established and the initial
command executed.
NOTE: if the library exits abnormally for any reason (for example, an abnormal termination of a program that is using
the API library), before the function pda300_Disconnect is called, the instrument’s front panel may still be locked out.
When the instrument’s front panel is locked out, all button presses will be ignored. The easiest way to recover from this
state is to cycle power to the instrument. If the instrument will still function correctly with the serial port, you could
call pda300_Connect, followed by pda300_Disconnect, which will clear the lockout.
prototype: int pda300_Connect(char *COMPortName);
parameters: char *COMPortName
For Windows platforms, this should be “COMn”, where n is any legal port numbered assigned by the operating system.
COMPortName must contain a NULL terminated string compatible with the C language. For languages other than
C/C++, the storage space pointed to should contain an array of characters, with the last character set to NULL (the
equivalent to ‘\0’, which is 0x00).
The API library will not be able to open the COM port if another program already has it open. For example, if you have
a Hyperterminal window connected to the PDA-300, you will encounter the following error condition when calling the
pda300_Connect function:
The function will return PDA300_SERIAL_COMM_ERROR.
The related error message will be: pda300_Connect: CreateFile failed with error 5.
The error 5 indicates that the Windows operating system returned the error ERROR_ACCESS_DENIED.
returns: PDA300_NO_ERROR | PDA300_SERIAL_COMM_ERROR | PDA300_NULL_POINTER |
PDA300_INVALID_FW_VERSION
If an error is returned, the function pda300_GetErrMessage can be called to retrieve a related error message.
example: int status;
status = pda300_Connect(“COM4”);
October 4, 2012 Sifos Technologies page
PDA-300 API Library Reference Manual
11
2.4.2. pda300_Disconnect
function: pda300_Disconnect
description: disables the lockout of the PDA-300 front panel, and closes the handle to the COM port. This function
will return PDA300_SERIAL_COMM_ERROR if a valid COM port connection was not established by a previous call
to pda300_Connect.
prototype: int pda300_Disconnect(void);
parameters: none
The function will return PDA300_SERIAL_COMM_ERROR.
returns: PDA300_NO_ERROR | PDA300_SERIAL_COMM_ERROR
If an error is returned, the function pda300_GetErrMessage can be called to retrieve a related error message.
example: int status;
status = pda300_Disconnect();
2.4.3. pda300_GetVersion
function: pda300_GetVersion
description: returns the version of the firmware read from the instrument when pda300_Connect was executed. NOTE:
no I/O is performed when this function is executed.
prototype: float pda300_GetVersion(void);
parameters: none.
returns: a floating point number, for example, 3.15.
example: float fwVersion;
fwVersion = pda300_GetVersion ();
2.4.4. pda300_GetHardwareVer
function: pda300_GetHarwareVer
description: returns the version of the hardware read from the instrument when pda300_Connect was executed. NOTE:
no I/O is performed when this function is executed.
prototype: int pda300_GetHardwareVer(void);
parameters: none.
returns: an integer number, for example 2.
example: int hwVersion;
hwVersion = pda300_GetHarwareVer ();
October 4, 2012 Sifos Technologies page
PDA-300 API Library Reference Manual
12
2.4.5. pda300_SetAlt
function: pda300_SetAlt
description: stores the defined ALT setting, to be used when detection or classification measurements are performed,
and when Vport is enabled. NOTE: no I/O is performed when this function is executed – this is a Library Settings
Only function.
The default ALT setting is ALT_A.
prototype: int pda300_SetAlt(pda300AltSetting Setting);
parameters: pda300AltSetting Setting - ALT_A | ALT_B
For any language that does not support enumerations, the value (ALT_A = 1, ALT_B = 2) should be passed as a 4-byte
(32-bit) integer.
returns: PDA300_NO_ERROR | PDA300_INVALID_PARAMETER_VALUE
If an error is returned, the function pda300_GetErrMessage can be called to retrieve a related error message.
example: int status;
status = pda300_SetAlt (ALT_A);
2.4.6. pda300_GetAlt
function: pda300_GetAlt
description: gets the stored ALT setting. NOTE: no I/O is performed when this function is executed – this is a Library
Settings Only function.
prototype: int pda300_GetAlt(pda300AltSetting *Setting);
parameters: pda300AltSetting *Setting - pointer to location to store the ALT setting in. The value stored
will be ALT_A | ALT_B (for a language that does not support enumerations ALT_A = 1, ALT_B = 2).
For any language that does not support enumerations, the pointer passed in should refer to a 4-byte (32-bit) integer
storage location.
returns: PDA300_NO_ERROR | PDA300_NULL_POINTER
If an error is returned, the function pda300_GetErrMessage can be called to retrieve a related error message.
example: int status;
pda300AltSetting Setting;
status = pda300_GetAlt (&Setting);
October 4, 2012 Sifos Technologies page
PDA-300 API Library Reference Manual
13
2.4.7. pda300_SetMdi
function: pda300_SetMdi
description: stores the defined MDI polarity setting, to be used when detection or classification measurements are
performed, and when Vport is enabled. NOTE: no I/O is performed when this function is executed – this is a Library
Settings Only function.
The default MDI polarity setting is MDI.
prototype: int pda300_SetMdi(pda300MdiSetting Setting);
parameters: pda300MdiSetting Setting - MDI | MDIX
For any language that does not support enumerations, the value (MDI = 1, MDIX = 2) should be passed as a 4-byte (32bit) integer.
returns: PDA300_NO_ERROR | PDA300_INVALID_PARAMETER_VALUE
If an error is returned, the function pda300_GetErrMessage can be called to retrieve a related error message.
example: int status;
status = pda300_SetMdi (MDIX);
2.4.8. pda300_GetMdi
function: pda300_GetMdi
description: gets the stored MDI polarity setting. NOTE: no I/O is performed when this function is executed – this is a
Library Settings Only function.
prototype: int pda300_GetMdi(pda300MdiSetting *Setting);
parameters: pda300MdiSetting *Setting - pointer to location to store the MDI setting in. The value stored
will be MDI | MDIX (for a language that does not support enumerations MDI = 1, MDIX = 2).
For any language that does not support enumerations, the pointer passed in should refer to a 4-byte (32-bit) integer
storage location.
returns: PDA300_NO_ERROR | PDA300_NULL_POINTER
If an error is returned, the function pda300_GetErrMessage can be called to retrieve a related error message.
example: int status;
pda300MdiSetting Setting;
status = pda300_GetMdi (&Setting);
October 4, 2012 Sifos Technologies page
PDA-300 API Library Reference Manual
14
2.4.9. pda300_SetEvents
function: pda300_SetEvents
description: stores the defined number of Classification events setting, to be used when classification measurements are
performed, and when Vport is enabled. NOTE: no I/O is performed when this function is executed – this is a Library
Settings Only function.
The default Events setting is TWO_EVENTS.
prototype: int pda300_SetEvents(pda300ClassEvents Setting);
parameters: pda300ClassEvents Setting - ONE_EVENT | TWO_EVENTS
For any language that does not support enumerations, the value (ONE_EVENT = 1, TWO_EVENTS = 2) should be
passed as a 4-byte (32-bit) integer.
returns: PDA300_NO_ERROR | PDA300_INVALID_PARAMETER_VALUE
If an error is returned, the function pda300_GetErrMessage can be called to retrieve a related error message.
example: int status;
status = pda300_ SetEvents (TWO_EVENTS);
2.4.10. pda300_GetEvents
function: pda300_GetEvents
description: gets the stored number of Classification events. NOTE: no I/O is performed when this function is
executed – this is a Library Settings Only function.
prototype: int pda300_GetEvents(pda300ClassEvents *Setting);
parameters: pda300ClassEvents Setting - pointer to location to store the ClassEvents setting in. The value
stored will be ONE_EVENT | TWO_EVENTS (for a language that does not support enumerations ONE_EVENT =
1, TWO_EVENTS = 2).
For any language that does not support enumerations, the pointer passed in should refer to a 4-byte (32-bit) integer
storage location.
returns: PDA300_NO_ERROR | PDA300_NULL_POINTER
If an error is returned, the function pda300_GetErrMessage can be called to retrieve a related error message.
example: int status;
pda300ClassEvents Setting;
status = pda300_GetEvents (&Setting);
October 4, 2012 Sifos Technologies page
Loading...