Create PC Software to Interface with Ansteron Board
This article describes how to create a PC application that can communicate with a program running on Ansteron Board. It can be used to build human-machine interface or giving computer the ability to access variety of sensors and physical devices. The communication is based on USB interface and all low level protocols will be handled by Ansteron's library to give developers a simple programming interface.
The library for PC application comes in form of a Dynamic Linking Library (DLL) of which functions can be called from different programming languages. The program running on Ansteron Board will handle electronic part and respond to commands from application running on PC. In this article, there are two similar example applications which will control the on-board LED, turning it on or off when user click a button. One of them is created using Visual Basic and the other one is C/C++ programming language. The program for Ansteron Board is built with Ansteron IDE and runs in both examples.
The basis for this connection is simple. Ansteron's Library provides PC application with functions to find attached Ansteron Board(s), open a connection and send or receive data from the board. Data sending to Ansteron Board will go to Serial Interface. The program running on Ansteron Board will then interpret that and act accordingly. Ansteron Board responds to PC application by sending data through Serial Interface.
2. PC Application library functions
The DLL file comes with Ansteron IDE, in folder "utilities/ansteron_usb". A copy of the file must be included in the same folder with PC application ".exe" file for it to work.
Find the number of connected Ansteron Board(s) on the system. Number of boards will be written to an integer variable giving to
ret_count input. The function return non zero value if succeeded, zero if failed.
Retrieve the serial of a board. Index starts from 0 to number of connected board minus 1. This function can be used to find a board by its serial number. The corresponding index of each serial number can be used to open the connection. If there is only one Ansteron Board on the system, this function is not needed. Serial is a string, usually has 12 characters. A non zero value will be returned if succeeded, zero if failed.
Open a connection to Ansteron Board. Index must be 0 if there is only one board on the system. If there are more boards, use function
ANSTERON_USB_get_board_serial() to find the right one by its serial. Baurate is the setting for Serial Interface and it must match with setting used in the program running on Ansteron Board. Enter 115200 if default setting is used. Other available values are: 9600,14400,19200,38400,56000,57600,115200. The function returns non zero value if succeeded, zero if failed.
Close current connection. This function must be called before Application exits.
Send a number of bytes to Ansteron Board. Input
buffer is the array of data. One or more bytes can be sent each time. The function returns non-zero value if succeeded, zero if failed.
ANSTERON_USB_get_data(buffer, max_size, expected, size_out,timeout);
Receive data sent from Ansteron Board and write to buffer. Input
max_size is the maximum number of byte the buffer can hold (It must be at least 24 bytes, this function will not return any data (even if data is available) when buffer is smaller than 24). Input
expected is the minimum number of bytes needed. If there is
expected number of bytes or more, the function will return with all available data bytes. If there is less than
expected number of bytes, the function will wait for a period of time given by
size_out will be written with number of bytes that was actually received and stored in buffer. The function return non-zero if succeeded or timeout (size_out is zero if time out). A zero value indicates an error or Ansteron Board has been removed.
Reset the CPU of Ansteron Board. Function returns non-zero if succeeded, zero if failed.
Return the voltage of CPU and DC input.
voltage_out will be written with a 32bit floating point value (
float type in C/C++ and
Single in Visual Basic). These functions return non-zero if succeeded, zero if failed.
3. Program for Ansteron Board
The program for Ansteron Board to work with PC applications is the same with other programs that use Serial Interface. It can repeatedly calling "
serial_get_byte()" to retrieve data from PC application. In an example below, the program will receive a byte and if that is zero, on-board LED will turn off. Any other values will turn on the LED. The program will send back value 32 to indicate that command succeeded.
4. Visual Basic
Visual Basic is an easy to use Rapid Application Development platform from Microsoft. Creating user interface is fast and simple with graphical tools. Programming language is Basic, which is pretty straight forward for developers from all technology areas. Visual Basic is free for download at Microsoft website. The latest versions usually come in bundle with other tools, included with Visual Studio.
Ansteron's Library for USB interface comes in a file name "ansteron_usb.dll". Visual Basic application can call functions of the library by importing them into program code. It can be done with appropriate declarations within the Form class. Note that a copy of DLL file must be put into the same folder with compiled application file (.exe).
The list below is functions of the library and their declarations in Visual Basic
Declare Function ANSTERON_USB_find_connected_boards Lib "ansteron_usb.dll" (ByRef count As UInteger) As Integer
Declare Function ANSTERON_USB_get_board_serial Lib "ansteron_usb.dll" (ByVal index As UInteger, ByVal serial() As Byte) As Integer
Declare Function ANSTERON_USB_open Lib "ansteron_usb.dll" (ByVal index As UInteger, ByVal bau As UInteger) As Integer
Declare Function ANSTERON_USB_close Lib "ansteron_usb.dll" () As Integer
Declare Function ANSTERON_USB_send_data Lib "ansteron_usb.dll" (ByVal data() As Byte, ByVal length As UInteger) As Integer
Declare Function ANSTERON_USB_get_data Lib "ansteron_usb.dll" (ByVal data() As Byte, ByVal max_length As UInteger, ByVal expected As UInteger, ByRef size_out As UInteger, ByVal timeout As UInteger) As Integer
Declare Function ANSTERON_USB_reset_CPU Lib "ansteron_usb.dll" () As Integer
Declare Function ANSTERON_USB_get_CPU_voltage Lib "ansteron_usb.dll" (ByRef voltage As Single) As Integer
Declare Function ANSTERON_USB_get_DC_input_voltage Lib "ansteron_usb.dll" (ByRef voltage As Single) As Integer
A simple user interface is created with two ratio buttons, ON and OFF. They are grouped in a container which will make one automatically uncheck when the other one is checked by user. There are also two labels, one will show serial of connected Ansteron Board, the other one will show CPU voltage.
All function declarations above will need to be added in to Form1 class in the source file.
The application will do these steps listed below. Visual Basic has event driven programming style and each subroutine is called when the event occurs.
- When the Application starts, it will look for connected Ansteron Board and start a connection.
- Whenever ON ratio button is checked, a value 255 will send to Ansteron Board, making the LED turn on. The Application will also check if value 32 is sent back, otherwise it will report an error. Similar routine is made for OFF button but the value sending is 0 instead of 255.
- When the Application is closing, it closes the connection with Ansteron Board.
These are the example code for each event, the first one is start up call:
Note that if there are more than one Ansteron Boards on the system, Application will need to scan through the list and pick out the one with given serial. Output of get serial function is an array of bytes, which will need to convert to string in order to compare with another string. Besides, use
string.Contains() method instead of comparing the strings explicitly.
The connection to Ansteron Board must be closed when Application unload.
Routine above is called when the state of ON ration button is changed. If button is checked, the Application will send value 255 to Ansteron Board and check for 1 byte returned. If no data is returned after 1 second or returned data is not 32, a error message will show. A similar routine is made for OFF button except sending data will be 0 instead of 255.
Here is the application running:
The example below explains how to create PC application using C/C++ in Visual Studio. The library comes with a library file (.lib) and C/C++ header file (.h) beside the DLL. They can be added in to the application instead of importing functions from DLL.
The library file ("ansteron_usb.lib") and header file ("ansteron_usb.h") will need to be copied into the same folder with other source files of the application. DLL file ("ansteron_usb.dll") must be also copied into the same folder with executable file of the application.
After a C/C++ Windows Application project is created in Visual Studio, compile the initial source once to make sure everything is working. Then in property page of the project, add library file into the list of additional dependences:
The header file will need to be included into source files where library functions will be called. In this example, header file is included into main source file.
Other global variables will then be added to store serial number, a sign to tell if Ansteron Board is ready or not. There are also handles for on and off buttons as well as handle of the main window.
The two buttons ON and OFF are created by calling Windows API. Their handles will be saved into global variables previously created. They will be used later to identify each button.
In the main message processing function, a routine for
WM_CREATE is added. This will be called when the Application starts. If there is Ansteron Board attached, the application will retrieve its serial and open a connection. The signal variable will be set to 1 when the connection is ready.
In the routine for
WM_DESTROY message, the connection to Ansteron Board is closed before the application exits.
WM_COMMAND will be sent when a button is clicked. In the routine below, application will check other parameters to identify which button sent the message. If ON or OFF button was clicked, their handle will come with the message. The application will then send 255 to Ansteron Board if ON button was clicked and 0 for other button. Checking returning value is also added to notify user if there was an error.
And this is the final program
In applications that require more functionalities as well as data integrity, exchanging data can be done in messages with error checking implemented.
When the connection to Ansteron Board is closed, interface chip on board will no longer driving RXD (pin D0) and the pin will goes from high (IDLE state of serial) to low level. This transition is equivalent to a start bit and Serial interface may recognize that as a zero byte.