ActiveWire USB
Software Reference
Ver. 1.0
28-Jan-03
1. Introduction
2. OCX methods
4. USB Protocol
5. ActiveBus
Thank you purchasing ActiveWire USB board.
This manual describes
ActiveWire software for the ActiveWire USB board.
Every information you need to install and use your ActiveWire USB software is
here in this manual.
Please refer to the ActiveWire USB Hardware Reference
for any information about ActiveWire USB board.
- Software Overview
Fig.1 Software Structure
- User Application
User application can be an Windows executable (.EXE) compiled from source code written in programming language, such as C, C++, Basic, Pascal, etc... Use API Library (.DLL) for the interface to the ActiveWire board.
User application can also be made with HTML and Script language. Use ActiveX Control (.OCX) for ActiveWire interface.
A HTML file with script can be browsed with your Internet browser and display customizable graphical interface to the board. - ActiveX Control (.OCX)
ActiveX Control provides ActiveWire interface to the Internet browser.script language in HTML.
Every functions in DLL are also implemented in OCX, so functions callable from .EXE can also called from HTML.
Note: Microsoft Internet Explorer 4.0 and above is currently supported with ActiveX interface. - API Library
API Library provides ActiveWire interface to the application.
It implements 3 basic functions for I/O port of the ActiveWire USB board, OutPort, InPort, and EnablePort.
It also implements low level USB interfaces for more precise control of the ActiveWire USB board. - WDM Driver
The driver (.SYS) provides the most fundamental interface to the Windows kernel. - Firmware Loader
Firmware loader loads firmware to the ActiveWire USB board when it is plugged in to the USB port.
Back to Index -
- Application Interface
This section describes functions of each ActiveWire API. - DLL functions
Please refer to DLL section of the reference manual of the programming language for how to use DLL in your source code. To get started, please refer to ActiveWire Tech.Note for notes on DLL.
Function declaration begins with __AWUSB_DLL, which is a macro defined as __declspec(dllimport) in header file, in AwusbAPI.h.
Each functions returns DWORD (unsigned long) Error code defined in AwusbAPI.h.
If the function call is successful, the return code is AWUSB_OK, or integer value 0.
- High level Application interface
-
__AWUSB_DLL DWORD AwusbOutPort
(BYTE *data, DWORD count);
Outputs count bytes to the port.
*data must point to at least count bytes size buffer.
Odd number bytes go to lower 8bits of the port.
Even number bytes go to higher 8bits of the port.
If count is >2, the data will be output o the port consecutively.
If the bit is enabled as output, writing 1 makes the corresponding header pin to high level, writing 0 makes the pin to ground level.
If the bit is not enabled (set to input), writing 0 or 1 does not make changes in level of the pin immediately, but it will take effect when the bit is enabled.
Default upon power up is all 0.
The device must be opened prior to this operation. -
__AWUSB_DLL DWORD AwusbInPort (BYTE
*data, DWORD count);
Inputs count bytes from the port.
*data must point to at least count bytes size buffer.
Data read indicates logical level of the port at the time.
Odd number bytes are read from lower 8bits of the port.
Even number bytes are read from higher 8bits of the port.
If count is >2, the port will be read consecutively.
If the bit indicates 1, it means the level of the corresponding header pin is logical high level.
If the bit indicates 0, it means the level of the pin is logical low.
The device must be opened prior to this operation.
NOTE: Application must always read Even number of bytes.
count must be divisible by 2. -
__AWUSB_DLL DWORD AwusbEnablePort
(BYTE *data, DWORD count);
Enables Output of the port.
*data must point to at least count bytes size buffer.
Odd number bytes enable to lower 8bits of the port.
Even number bytes enable to higher 8bits of the port.
Writing 1 sets the corresponding bit of the port to output.
Writing 0 sets the corresponding bit of the port to input.
Default is all input.
The device must be opened prior to this operation.
- Low level USB interface
-
__AWUSB_DLL DWORD AwusbOpen (DWORD
devnum);
Opens the USB device with the device number specified by devnum.
Device number is integer number assigned by the operating system.
The first board plugged in becomes 0, the second becomes 1, the third becomes 2, ... and so on.
To open the first board, call this function with devnum = 0.
Following Open operation to the same device number will fail.
One thread can open one device at a time.
If your application needs to open 2 or more devices, create threads, load DLL in each thread, then open device with different devnum.
Close device when finished using the device by calling AwusbClose () function described below. -
__AWUSB_DLL DWORD AwusbClose ();
Close the USB device previously opened by AwusbOpen() operation.
Closing the device makes the device available for openning by any other thread.
The device must be opened prior to this operation. -
__AWUSB_DLL DWORD AwusbSetInterface
(DWORD intfc, DWORD altset);
Sets USB interface of device to Interface intfc, Alternate setting altset.
Interface intfc and Alternate setting altset must be implemented by the device
See following section 4. USB Protocol for more detail.
The device must be opened prior to this operation.
Default upon powered up is Interface 0 and Alternate setting 0. -
__AWUSB_DLL DWORD AwusbRead (DWORD
pipenum, BYTE *buf, DWORD count);
Reads count bytes of data from the USB pipe specified by pipenum.
*buf must point to at least count bytes size buffer.
The pipe must be IN pipe.
Reading from OUT pipe will cause unexpected results.
Depending on pipenum implemented by each device, there may be restriction in arguments, such as count must be even number.
See following section 4. USB Protocol for more detail
The device must be opened prior to this operation. -
__AWUSB_DLL DWORD AwusbWrite (DWORD
pipenum, BYTE *buf, DWORD count);
Writes count bytes of data to the USB pipe specified by pipenum.
*buf must point to at least count bytes size buffer.
The pipe must be OUT pipe.
Writing to IN pipe will cause unexpected results.
Depending on pipenum implemented by each device, there may be restriction in arguments.
See following section 4. USB Protocol for more detail
The device must be opened prior to this operation. -
__AWUSB_DLL DWORD AwusbCancelIo
(DWORD pipenum);
This function is currently not implemented.
It will return error if called. -
__AWUSB_DLL DWORD AwusbGetPipeInfo
(AWUSB_PIPEINFO *pipeinfo);
Gets Pipe information from the opened device and stores in an AWUSB_PIPEINFO structure pointed by *pipeinfo.
AWUSB_PIPEINFO structure is defined as below in AwusbAPI.h.
#define AWUSB_MAX_NUMPIPE 32
typedef struct _AWUSB_PIPEINFO_T
{
BYTE numpipe;
BYTE type[AWUSB_MAX_NUMPIPE];
BYTE endpoint[AWUSB_MAX_NUMPIPE];
BYTE dir[AWUSB_MAX_NUMPIPE];
WORD size[AWUSB_MAX_NUMPIPE];
} AWUSB_PIPEINFO;
Following describes each member of the structure.
BYTE numpipe;
Number of pipes implemented in this interface.
numpipe elements of following arrays are valid.
BYTE type[AWUSB_MAX_NUMPIPE];
Type of each pipe. BYTE (unsigned char) should be interpreted as follows.
0 : Control endpoint
1 : Isochronous endpoint
2 : Bulk endpoint
3 : Interrupt endpoint
BYTE endpoint[AWUSB_MAX_NUMPIPE];
Endpoint address of the pipe.
Number between 0 and 15.
BYTE dir[AWUSB_MAX_NUMPIPE];
Direction of the pipe.
0 : OUT endpoint
1 : IN endpoint.
WORD size[AWUSB_MAX_NUMPIPE];
Maximum USB packet size of the pipe.
Number between 0-1024 when endpoint type is Isochronous.
Number between 0-64 when endpoint type is other than Isochronous. -
__AWUSB_DLL DWORD AwusbResetPipe
(DWORD pipenum);
Reset the pipe specified by pipenum.
The device must be opened prior to this operation. -
__AWUSB_DLL DWORD AwusbDownload
(AWUSB_INTELHEX hexrec);
Download ActiveWire USB Firmware stored in an AWUSB_INTELHEX structure, hexrec in to the opened device.
AWUSB_INTELHEX structure is defined as below in AwusbAPI.h.
typedef struct _AWUSB_INTELHEX_T
{
BYTE count;
WORD addr;
BYTE type;
BYTE data[256];
BYTE crc;
} AWUSB_INTELHEX;
Each member corresponds to each field of Intel Hex file format.
See ActiveWire TechNote for more detail about Intel Hex file format
Following describes each member of the structure.
BYTE count;
number of bytes to download to ActiveWire USB Internal RAM.
Must be less than 256.
WORD addr;
Start address where data will be written to.
Address must be between hex 0000 and hex 1B19.
BYTE type;
type == 1 indicates that there is no more data to download.
If type == 1, Data in data[256] will be ignored.
BYTE data[256];
Data to be written to ActiveWire USB Internal RAM.
BYTE crc;
check sum -
__AWUSB_DLL DWORD
AwusbReadIntelHexLine (char *buf, AWUSB_INTELHEX *hexrec);
Read one line from character string in Intel Hex format, and stores data to an AWUSB_INTELHEX structure pointed by *hexrec.
Refer to an example code below.
DWORD ret;
FILE *fp;
char buf[1024];
AWUSB_INTELHEX hexrec;
fp = fopen (filename, "rt");
if (! fp)
return (AWUSB_ERROR_FILEOPEN);
while (!feof (fp))
{
fgets (buf, 1024, fp); // read one line
ret = AwusbReadIntelHexLine (buf, &hexrec); // break down ASCII characters and store in struct
if (ret != AWUSB_OK)
return (ret);
if (hexrec.type == 0x01)
break;
ret = AwusbDownload (hexrec);
if (ret != AWUSB_OK)
return (ret);
}
-
__AWUSB_DLL DWORD Awusb8051Reset
(BOOL hold);
Resets the ActiveWire USB microcontroller.
if hold == TRUE, the reset will be held active until next call of this function with hold == FALSE.
Holding the microcontroller reset will cause the ActiveWire USB board to be deactivated.
During microcontroller is reset, there would be only one pipe, Control endpoint, is accessible through USB.
if hold == FALSE, the reset will be asserted momentarily, then the microcontroller starts running from cold boot.
When microcontroller started running, host negotiates with the device on USB bus, then operating system recognizes the device is ready.
-
__AWUSB_DLL DWORD
AwusbDownloadIntelHexFile (char *filename);
Download ActiveWire USB Firmware file specified by *filename.
The firmware file, *filename, must be in Intel Hex file format.
Refer to ActiveWire TechNote for more detail about Intel Hex file format
This function is implemented by using above AwusbDownload(), AwusbReadIntelHexLine() and Awusb8051Reset() functions in proper sequence.
- Error handling
-
__AWUSB_DLL char *
AwusbErrorMessage (DWORD errcode);
Converts ActiveWire defined error code to a human readable character string.
Refer to an example code below.
DWORD devnum = 0;
DWORD ret;
ret = AwusbOpen (devnum); // Open USB device
if (ret != AWUSB_OK) // if error
printf ("%s\n", AwusbErrorMessage (ret)); // get error message
else
printf ("Device #%ld : Open successfully.\n", devnum);
...
4.
3. Application Interface (Cont'd)
- OCX methods
ActiveWire USB ActiveX Control (.OCX) has been implemented based on DLL API specification.
All functionalities in DLL API is available in OCX.
Following is a summary of difference between DLL and OCX.
- OCX methods returns NULL string upon success, Error message string if any.
- OutPort/InPort/EnablePort will access data 2 bytes at a time.
- 3 additional methods, OutPortBlock/InPortBlock/EnablePortBlock are implemented in OCX to support multi-words transfer.
- BSTR OutPort (long dat);
Provides the similar functionality of corresponding DLL functions, except that this takes only 1 long argument, and lower 16bits of the arguments will be output to the I/O pins.
Please note that these is no count argument to indicate number of bytes to transfer as oppose to the corresponding DLL function.
Returns human readable error message as a string when an error occurred.
Returns Null string when successful. - long InPort ();
Provides the similar functionality of corresponding DLL functions, except that there is no arguments, and returns long data with current logical state of I/O pins in lower 16bits.
Please note that these is no argument at all as oppose to the corresponding DLL function.
Returns negative number when error occurred. Pass that returned negative number to ErrorMessgae() method to retrieve human readable error message. - BSTR EnablePort (long
dir);
Provides the similar functionality of corresponding DLL functions, except that this takes only 1 long argument, and lower 16bits of the arguments to enable output of the I/O pins. 1 in corresponding bits enables output, 0 makes it input.
Please note that these is no count argument to indicate number of bytes to transfer as oppose to the corresponding DLL function.
Returns human readable error message as a string when an error occurred.
Returns Null string when successful. - BSTR Open (long devnum);
- BSTR Close ();
- BSTR SetInterface (long
intrfc, long altset);
These provide the same functionality of corresponding DLL functions.
Refer to DLL functions section above.
Returns human readable error message as a string when an error occurred.
Returns Null string when successful. - BSTR Read (long pipenum,
long count);
Read count bytes of data from USB pipe specified by pipenum, then returns pointer to formatted character string.
An example of string returned by the method looks like below.
ff ff 01 02 (2 digits hex value separated by a space)
Returns human readable error message as a string when an error occurred.
Returns Null string when successful. - BSTR Write (long
pipenum, LPCTSTR data, long count);
Read hex values from character string data, then send count bytes of data to the USB pipe specified by pipenum.
If data string is too short and less than count bytes could be read from data string, it will send repeated data.
Following example will send 8bytes of data, ff, ff 00, 00, ff, ff, 00, and 00.
data = "ff ff 00 00";
Write (1, data, 4);
Returns human readable error message as a string when an error occurred.
Returns Null string when successful. - BSTR CancelIo (long
pipenum)
These provide the same functionality of corresponding DLL functions.
Refer to DLL functions section above.
Returns human readable error message as a string when an error occurred.
Returns Null string when successful. - BSTR GetPipeInfo ();
Returns Pipe information available for the interface in formated character string.
Returns human readable error message as a string when an error occurred. - BSTR ResetPipe (long
pipenum);
Provides the same functionality of corresponding DLL function.
Refer to DLL functions section above.
Returns human readable error message as a string when an error occurred.
Returns Null string when successful. - BSTR Download (LPCTSTR
filename);
Provides the same functionality of AwusbDownloadIntelHexFile() function in DLL API.
Refer to DLL functions section above.
Returns human readable error message as a string when an error occurred.
Returns Null string when successful. - BSTR Reset8051 (long hold);
Provides the same functionality of corresponding DLL function.
Refer to DLL functions section above.
Returns human readable error message as a string when an error occurred.
Returns Null string when successful. - BSTR ErrorMessage (long
error_code);
Provides the same functionality of corresponding DLL function.
Refer to DLL functions section above.
Since each method returns already formated error message when any error happened, this methods will not used in HTML script. - BSTR OutPortBlock
(LPCTSTR buf, long count);
Read hex values from character string buf, then send count bytes of data to the ActiveWire I/O port.
If data string is too short and less than count bytes could be read from data string, it will send repeated data.
Following example will toggle all 16bits of I/O port up, down up and down.
data = "ff ff 00 00";
OutPortBlock (data, 8);
Returns human readable error message as a string when an error occurred.
Returns Null string when successful. - BSTR InPortBlock (long
count);
Read count bytes of data from ActiveWire I/O port, then returns pointer to formatted character string.
An example of string returned by the method looks like below.
ff ff 01 02 (2 digits hex value separated by a space)
Returns human readable error message as a string when an error occurred.
Returns Null string when successful. - BSTR EnablePortBlock
(LPCTSTR buf, long count);
Read hex values from character string buf, then send count bytes of data to the ActiveWire I/O port enable register.
If data string is too short and less than count bytes could be read from data string, it will send repeated data.
Following example will enable all 16bits of output port twice momentarily, then put them back to input mode.
data = "ff ff 00 00";
EnablePortBlock (data, 4);
Returns human readable error message as a string when an error occurred.
Returns Null string when successful.
5. USB
Protocol
Please
email <enginfo@ActiveWireInc.com> for more information.
Back to Index
6.
ActiveBus
Please
email <enginfo@ActiveWireInc.com> for more information.
Back to Index
7. Frequently
Asked Questions
Please
see our web site.
Back to Index
8. Revision
History
ver. 0.9 17-May-1999 First release.
ver. 0.91 24-May-1999 Fixed InPort()
OCX method mulfunction problem.
Changed
InPort() OCX method argument and return value.
ver. 1.0 28-Jan-03 Minor
changes.
Back to Index