Installing

Installing The Server

• You may need to change BIOS settings to not stop on keyboard errors, and to start up when power is applied.
• Install Windows XP.
• Install drivers as needed to get ethernet working. We needed the network adapter drivers from Intel's download center.
• Configure the network connection's TCP/IP for a fixed IP address, for example 10.1.1.42.
• Install the ACCES USB drivers. Most convenient is probably the web installer. One install gives you the drivers for USB-DI16A, USB-DO16A, and USB-DIO-16A boards (and others).
• Plug in the ACCES USB boards. The Found New Hardware wizard may pop up twice per board; do not check Windows Update, then install automatically.
• Copy EDIOServer.exe to the system. It can go pretty much anywhere, for example in C:\Program Files\ACCES\.
• Use the right mouse button to right-drag EDIOServer.exe into the Start Menu, into All Programs, and into Startup. When you let go, a menu will pop up, click Create Shortcuts Here.
• Open the following ports in Windows Firewall: 60672, 60688, 60689, 60690. To allow for future expansion, you may wish to open the whole 60672-60703 range.
• For "testing mode", you can run EDIOServer.exe, then click View Status. If nothing is wrong, each listed port will have "ENet listening" and "DIO working", followed by DIO frequency (either "External/Off" or a Hz value), packet bits setting, and number of packets queued. A read port will also indicate its packet state: "Not Yet" if its enable bit hasn't been low yet, "Between Packets" most of the time, and "Receiving Packet" if the status poll happened to catch it in the middle of receiving a packet. If a client is connected to a port, the connection(s) will be listed after "ENet listening".
• For actual use, shut down, unplug keyboard and mouse, and turn back on.

Installing The Client

Copy AIOEDIO.dll next to the program that will use it (or to the 32-bit system directory, or anywhere else the program can find it).

Client API

The general sequence is:

• AED_Connect() to open a connection.
• AED_SetFreq() to set the device's clock frequency (optional).
• AED_SetPacketBits() to set the number of bits in the device's packets (optional).
• AED_SetTimeout() to set the connection's timeout (optional).
• AED_Go() to start acquisition.
• Repeated calls to AED_GetAllPackets() or AED_GetLatestPacketAndDiscard() for a read port, or AED_PutData() for a write port, to actually transfer data.
• AED_Close() to close the connection when done.

If the connection fails during operation, a new connection can be swapped in, like this:

• AED_Close() to close the old connection.
• AED_Connect() to open a new connection.
• AED_SetTimeout() to set the connection's timeout (optional).
• Resume with the calls to AED_GetData() or AED_PutData().

The server serializes and deserializes packets in Intel (little-endian) bit order. For example, if the first 8 bits of a packet are 0 1 0 1 1 0 1 1, then the first byte of the packet is 0xDA.

AED_Connect()

AED_Connect() connects to the specified device on the specified host. It returns a client reference (like a handle) that represents the connection, or zero on a failure. Before data can be read or written, AED_Go() must be called.

Host can be an IP address in dotted decimal string form (like "10.1.1.42"), a DNS name (like "dio.overthere.com"), or a name in the HOSTS file (like "localhost").

bReadPort should be nonzero to connect to the port for an input board on the host, or zero to connect to the port for an output board.

Index is a zero-based index of the port, separate for read and write ports. The current design has three read ports (index 0, index 1, index 2) and one write port (index 0).

The returned client reference is opaque — just a 4-byte value that you pass to the other AED_* APIs when dealing with that connection. While this is similar to a handle, it doesn't work with any handle-specific APIs, like GetHandleInformation() or CloseHandle(). On a failure, the returned reference will be zero, and the associated Windows error code can be retrieved via GetLastError(). Error codes include:

• ERROR_NOACCESS if the string pointed to by Host can't be accessed.
• ERROR_NO_NETWORK if no socket could be created at all.
• ERROR_NO_NET_OR_BAD_PATH if the connection could not be established.

The server does allow more than one client to connect to a single device. This feature is intended for recovery from network problems, but does allow (for example) two programs to connect, one that reads data and one that changes clock frequency.

AED_SetFreq()

AED_SetFreq() sets the clock frequency of a device.

Hz is the clock frequency to set the board to. For external/slave operation, use 0. The default at power-on is external/slave, but this setting is remembered by the server while powered on.

The return value is ERROR_SUCCESS (equal to zero) on success, or another Windows error code on failure. Error codes include:

• ERROR_INVALID_HANDLE if the client reference is invalid.
• ERROR_NOT_CONNECTED if the connection has closed, usually a networking issue. (To reconnect, close this client ref and call AED_Connect() to get a new one.)
• ERROR_INTERNAL_ERROR if an error occurred while assembling the outgoing network packet. This probably indicates insufficient memory available.

AED_SetPacketBits()

AED_SetPacketBits() sets the number of bits in the device's packets. This also sets the number of bytes to one-eighth (round up) the number of bits. While AED_GetData() and AED_GetLatestPacketAndDiscard() get one packet, and therefore don't need a fixed packet size, the current packet bytes is used for the array filled in by AED_GetLatestPacketAndDiscard(), and the current packet bits is used by packets sent with AED_PutData(). The server will truncate or zero-pad as needed.

NewPacketBits is the new packet size, in bits. The default at power-on is 176, but this setting is remembered by the server while powered on.

The return value is ERROR_SUCCESS (equal to zero) on success, or another Windows error code on failure. Error codes are mostly covered under AED_SetFreq(), but also include:

• ERROR_BAD_LENGTH if NewPacketBits is zero or negative.

AED_SetBlockSize()

AED_SetBlockSize() sets the block/frame size for DIO_StreamFrame() reads. In this high-responsiveness design, the default minimum block size is ideal, so it's generally best to leave it alone. If called while the server's acquisition loops are running, this setting will take effect after the current block finishes.

SizeBytes is the new block size, in bytes. It will be rounded up to the next multiple of 512. The default at power-on is 512, but this setting is remembered by the server while powered on.

The return value is ERROR_SUCCESS (equal to zero) on success, or another Windows error code on failure. Error codes are mostly covered under AED_SetFreq(), but also include:

• ERROR_BAD_LENGTH if SizeBytes is zero or negative.

AED_SetTimeout()

AED_SetTimeout() sets the inter-receive timeout for reply network packets. This is a client setting, and thus setting it doesn't involve network traffic.

TimeoutMS is the new timeout, in milliseconds. The default for a new connection is 2000.

The return value is ERROR_SUCCESS (equal to zero) on success, or another Windows error code on failure. Error codes are mostly covered under AED_SetFreq(), but also include:

• ERROR_BAD_LENGTH if TimeoutMS is zero or negative.

AED_SetAZero()

AED_SetAZero() sets the first "medium-speed" digital bit on a device.

bNewBit is interpreted as a boolean, true to set the bit high, false to set it low. The default at power-on is high, but this setting is remembered by the server while powered on.

The return value is ERROR_SUCCESS (equal to zero) on success, or another Windows error code on failure. Error codes are covered under AED_SetFreq().

AED_SetMDIO1()

AED_SetMDIO1() sets one of the "medium-speed" digital bits on a device.

Index indicates which bit to set. Port A has bits 0-7, port B has bits 8-11, port C has bits 16-18. Port D technically has bits 24-26, but it's in input mode, and writes to input bits are ignored. Any bit 0-31 is accepted, but other bits in this range are unoccupied.

bNewBit is interpreted as a boolean, true to set the bit high, false to set it low. The default at power-on is high, but this setting is remembered by the server while powered on.

The return value is ERROR_SUCCESS (equal to zero) on success, or another Windows error code on failure. Error codes are mostly covered under AED_SetFreq(), but also include:

• ERROR_INVALID_INDEX if Index is 32 or more.

AED_Go()

AED_Go() starts the server's acquisition loops. This is necessary before data can be read or written; the block size will be used at this time, and should be set first.

The return value is ERROR_SUCCESS (equal to zero) on success, or another Windows error code on failure. Error codes are covered under AED_SetFreq().

AED_GoClear()

As AED_Go(), except the various buffers are cleared first as for AED_Clear().

AED_Clear()

Clears the various buffers in the server. If the server was already acquiring a slow block, that block will finish first (so it can be cleared).

The return value is ERROR_SUCCESS (equal to zero) on success, or another Windows error code on failure. Error codes are covered under AED_SetFreq().

AED_GetLatestPacketAndDiscard()

AED_GetLatestPacketAndDiscard() gets the latest packet from a read port, along with its timestamp, and discards any other queued packets. If no packets are available in the port's queue, it will return a zero-length success.

pTimestampDataBytes is a pointer to a variable that holds the size of the variable pointed to by pTimestampData, in bytes. On return, this variable will be set to the bytes of timestamp read. Both should be 8 when functioning properly.

pTimestampData is a pointer to an IEEE double-precision floating-point variable to read the timestamp into. The timestamp is a TDateTime, equal to days since the 30th of December 1899, according to the server's system clock.

pPacketDataBytes is a pointer to a variable that holds the size of the buffer to read a packet into, in bytes. On return, this variable will be set to the bytes of packet read.

pPacketData is a pointer to the buffer to read a packet into.

The return value is ERROR_SUCCESS (equal to zero) on success, or another Windows error code on failure. Some error codes are covered under AED_SetFreq(), but also include:

• ERROR_BAD_TOKEN_TYPE if trying to read from a write port.
• ERROR_BAD_LENGTH if a variable pointed to by pTimestampDataBytes or pPacketDataBytes is zero or negative.
• ERROR_TIMEOUT if there was a timeout waiting for the reply.
• ERROR_READ_FAULT or ERROR_INVALID_DATA if the reply network packet was not interpretable. This may mean the network stream is corrupt; if it persists, close this client ref and call AED_Connect() to get a new one.
• ERROR_BAD_NET_RESP if there was an error on the other end; use GetLastError() to tell what the error was. This likely means the server app can't talk to the board, and requires restarting it.
• ERROR_BAD_DEV_TYPE if the local and remote read flags are out of sync. This is unlikely, and best solved by closing the client ref and calling AED_Connect() to get a new one.

AED_GetAllPackets()

AED_GetAllPackets() gets all packets queued on a read port, along with their timestamps. If no packets are available in the port's queue, it will return a zero-length success.

pTimestampDataBytes is a pointer to a variable that holds the size of the buffer to read timestamps into, in bytes. On return, this variable will be set to the bytes of timestamps read.

pTimestampData is a pointer to the buffer to read timestamps into, seen as an array of IEEE double-precision floating-point values. Since the max queue depth is currently 400, it is perhaps ideal for this to be an array of 400 (3 200 bytes).

pPacketDataBytes is a pointer to a variable that holds the size of the buffer to read packets into, in bytes. On return, this variable will be set to the bytes of packets read.

pPacketData is a pointer to the buffer to read packets into, seen as an array of packet structs. Each packet struct has the same size, given by the current packet bytes. Since the max queue depth is currently 400, it is perhaps ideal for this to be an array of 400; with 176-bit (22-byte) packets, that comes to 8 800 bytes.

The return value is ERROR_SUCCESS (equal to zero) on success, or another Windows error code on failure. Error codes are covered under AED_GetLatestPacketAndDiscard().

AED_GetData()

AED_GetData() gets the oldest packet from a read port. If no packets are available in the port's queue, it will return a zero-length success. This function is deprecated in this high-responsiveness design.

pDataBytes is a pointer to a variable that holds the size of the buffer to read into, in bytes. On return, this variable will be set to the amount of data read.

pData is a pointer to the buffer to read into.

The return value is ERROR_SUCCESS (equal to zero) on success, or another Windows error code on failure. Error codes are covered under AED_GetLatestPacketAndDiscard(), except there's one pDataBytes in place of pTimestampDataBytes and pPacketDataBytes.

AED_PutData()

AED_PutData() writes a packet to a write port. If this packet is smaller than the current packet bits, it will be truncated; if larger, it will be zero-padded.

pDataBytes is a pointer to a variable that holds the size of the buffer to write from, in bytes. On return, this variable will be set to the amount of data written.

pData is a pointer to the buffer to write from.

The return value is ERROR_SUCCESS (equal to zero) on success, or another Windows error code on failure. Error codes are mostly covered under AED_SetFreq() and AED_GetData(), but also include:

• ERROR_BAD_TOKEN_TYPE if trying to write to a read port.
• ERROR_NOACCESS if an error(usually an access violation) occurred while trying to access the buffer pointed to by pData.

AED_Close()

AED_Close() closes a client reference, disconnecting the connection and cleaning up any memory used. After being passed to AED_Close(), the client reference is invalid.

EEPROM Reference

Each device has a specific value in the first four bytes of the EEPROM, which the server looks for. In order to facilitate field replacements, these values are listed below (in hex):

These EEPROM addresses are relative to the user-programmable space, as seen by eWriter.exe, GetDeviceByEEPROMByte(), CustomEEPROMRead(). If using "raw" EEPROM access, e.g. by sending arbitrary USB requests, you'll need to add 1E00, producing absolute addresses 1E00, 1E01, 1E02, and 1E03.