There is a fundamental difference between a 'programming guide' and a 'reference'. A reference tells tells you the specifics of how to use a particular funcion, but it usually assumes that you have a clear view of the 'big picture' of how to use the API. A programming guide does not usually provide much detail; its purpose is to teach the programmer how to use the API in a general sense. It presents a general description of when and how you call the functions. That is what is presented below. Don't forget to download and examine the sample code as well, as that can yield some valuable insight into using the API.
Before you can use the API, you must learn how to call the API functions from your programming language. To learn how to do this click here.
This guide is written with the C programming language in mind, but Visual Basic users will benefit as well. Note that nearly every API function has an equivalent Visual Basic object method. The documentation for each function has a section at the bottom which explains the Visual Basic equivalent. So as you read this guide, notice the general programming procedure; it will then be simple to apply this knowledge to Visual Basic.
You will notice that every API function provided in the API begins with "ser_sr24_". The "ser" stands for 'serial', while the "sr24" means that the function is for the board we built in the magazine article. This naming convention simply helps to indicate that the functions are part of the serial board API. Hopefully this will reduce some confusion for programmers.
Once you have learned how to access the API functions in your programming language, you may begin programming and using your serial I/O board. The first step is to 'open' the card for use by calling the ser_sr24_open() function and passing it parameters such as which serial port to use and the desired baud rate. The ser_sr24_open() function initializes the serial board and returns a new "handle" which identifies the board which was opened. This handle will be used throughout the program to identify this board. The programmer must have the handle to call other API functions which perform an operation on the board. A valid handle tells the other API functions everything they need to know about how to access the serial board. If there is a conflict or error while opening or initializing the serial board, the ser_sr24_open() function returns an error code instead of a valid handle.
As you know, the serial board can be configured to operate in several different modes. Now that you have 'opened' the board and have a valid handle, you need to configure the board for your particular project. The I/O ports can be configured using the ser_sr24_set_portmode() function. This lets you set the mode as digital/analog, set the direction as input/output, or tri-state the port. When you call this function, you must pass it a valid serial board handle as returned from ser_sr24_open(), the port you want to configure, the property you want to set, and the value you want to set it to.
If you plan to use the hardware events feature of the board, you must tell the serial board which ports or bits to report events for. You do this by calling the ser_sr24_register_event() function and passing it a valid handle, which port you are are interested in, and which bit in particular you want to report events for. You also need to pass a user-defined ID value which will be used to identify the event when it occurs. Call ser_sr24_register_event() once for every bit or port for which you want to configure event reporting.
We have just told the serial board to monitor certain bits for hardware events. When hardware events occur, we want a section of our application code to execute. This section of code is referred to as an 'event handler', since it gets called automatically by the API in response to a hardware event. In the event handler, you will write code which takes some sort of action in response to the event. For example, if a button was pressed, you might want to write code to turn on a motor. In order for all this to work correctly, the API needs to know which function in your code is the event handler; therefore, you must 'register' an event handler with the API by calling the ser_sr24_set_event_handler() function and passing it a valid serial board handle and a data structure specifying information about your event handler code. If you are not using the hardware events feature of the board, you don't have to worry about registering an event handler.
Now that the serial board is configured, you can write and read data very easily. The API provides both bit-level and byte-level functions for reading and writing data. The ser_sr24_input_byte() and the ser_sr24_output_byte() functions provide the byte-level access to the I/O ports, while ser_sr24_input_bit() and ser_sr24_output_bit() provice bit-level access. Both the bit-level and byte-level functions access the same ports, and have the capability to do the same things. The two different types of functions are simply provided for convenience. For example, if the state of one particular bit of an output port must be changed, it is much easier to use the bit-level function than the byte-level function.
If the board has been configured for analog inputs, then an analog input can also be easily read by using the ser_sr24_input_analog() function.
When an input pin or port changes state, this is referred to as a hardware event. The serial board can be configured to detect these events and report them to the host PC, which then automatically executes a section of your code. To get this all configured, you must first tell the API what code routine should be executed when a hardware event occurs. You do this by calling the ser_sr24_set_event_handler() function. You then must register all the events that you are interested in. For example, if you want to know when Port 1 changes, you must configure the serial board to report this. Call the ser_sr24_register_event() function for each event you want to register. Anytime you register an event, you will need to pass an event ID number to the function. This ID will be passed to your event handler when the event occurs; in this manner, the event handler can determine which particular event occurred.
You should now be all set to go. Your event handler will now execute whenever a registered hardware event occurs. One more function which you may find useful is the ser_sr24_wait_event() function. You can call this function to cause your program to wait for the specified event to occur.
Before terminating your program, you should
call the ser_sr24_close() function to close the
serial board.
Back to Contents | Winford Engineering (2000) |