Winford Engineering Portal API Overview

Overview of the Winford Engineering Portal API

Winford Engineering is pleased to provide an API for programming and controlling Winford Engineering's complete line of Portal I/O cards. This overview is intended to show how different functions of the API work together. To gain a better understanding of the individual functions, you should access specific function documentation from the reference page. Also you should check the programming guide for the card model that you have.

What is the API and why do I need it?

API stands for Application Programming Interface. This API is a set of functions and routines provided to you, the programmer and user, to make the use of Winford's I/O Cards easy, reliable, and consistent. Although I/O cards may be directly programmed by using low-level input and output functions, the API provides a more intuitive method. When using the Portal API, the programmer does not need to know how the card works nor how to use the card with low-level input and output functions. Because the programmer doesn't need to keep track of numerous details, the API helps to avoid frustrating mistakes and bugs.

How do I use the Portal API?

Before you can create programs using the API, you must do two things: install it on your system, and learn how to call the API functions from your programming language. (As a note, every function provided in the API begins with "we_". The "we" stands for Winford Engineering. This small prefix indicates that a function is part of Winford's API. Hopefully this will reduce some confusion for programmers.) Once you have access to the API functions, you may begin programming and using your Portal I/O cards. The first step in using any card is to call the we_OpenCard function, telling the API what card model you have and what base address it is configured for. The we_OpenCard function initializes the card and returns a new "handle" to the programmer. A handle is a number generated by the API (in this case by the we_OpenCard function) to identify the newly opened card. The programmer must have the handle to call other API functions which perform an operation on the card. A valid handle tells the other API functions what card model and base address the programmer is using. If there is a conflict or error while opening or initializing the card, the we_OpenCard function returns an error code instead of a valid handle. After the card has been successfully opened, you may use the handle as a parameter to most of the other API functions.

Most I/O cards can be configured in different ways. For example, the CRD155B has 3 ports that can be individually configured as inputs or outputs. In order to configure your card after opening it, you may call the we_ConfigureCard function. In addition to the handle, you must tell the function which port you want to configure and what mode you want that port to be set up for.

Now all that you must do to actually use the card is to call the we_OutputValue or we_InputValue functions, which write a value out to the port, or read in a value, respectively. You must tell these functions which port you want to write to or read from. If a port is currently configured for input, we_OutputValue will return an error code, and the value will not be written to the port. Similarly, if a port is configured for output, we_InputValue will return an error code.

When a port is configured for output, the last value written to an output port can be read back using the we_ReadBack function. It is never necessary to use this function. However, if you need to know the current state of an output port, this function may be useful.

When you are done using the card, you should call the we_CloseCard function. This causes the Portal API to release any information it has stored about the card, and indicates that the card is available for use. If the card has not been closed using we_CloseCard any following attempt to reopen the card using we_OpenCard within the same application instance will fail due to conflict. (Note that when your application terminates, the API is unloaded causing all cards to be closed.) There is an additional function provided for convenience called we_CloseAllCards. This function causes any cards that the Portal API has opened to be closed. This allows the cards to then be reopened using we_OpenCard.