ACCES “ETH Series” Software Reference

Our ETH-DIO-48 and related distributed I/O boards share a programming interface at both the Windows/DLL level, and at the raw Ethernet TCP packet level.

When operating these devices in Windows-based operating systems we highly recommend using the provided AIOETHW.dll. You can examine the source for the DLL in your {sample path}/AIOETHW.src/DLL directory.

The raw Ethernet TCP packets are described towards the bottom of this document.

Windows API DLL, AIOETHW

To install the client, simply copy AIOETHW.dll next to the program that will use it, or to the 32-bit system directory.

The general sequence to use it is:

• AEW_Connect() to open a connection.
• Optionally, AEW_SetTimeout() to set the connection's timeout.
• AEW_DIO_Configure() to set the initial configuration, and disable the tristate.
• Repeated I/O calls, using AEW_DIO_WriteAll()/AEW_DIO_Write1(), AEW_DIO_ReadAll(), and possibly AEW_DIO_Configure() to change the configuration.
• Optionally, AEW_DIO_ReadAll() to read data.
• Optionally, AEW_GetStatus() to check the device's status.
• AEW_Disconnect() to close the connection when done.

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

• AEW_Disconnect() to close the old connection.
• AEW_Connect() to open a new connection.
• Optionally, AEW_SetTimeout() to set the connection's timeout.
• Resume with the I/O calls.

AEW_Connect()

AEW_Connect() connects to the specified host device. It returns a client reference (like a handle) that represents the connection, or zero on a failure.

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

Index is normally 0. This connects to port 51936; other values are reserved for future expansion.

The returned client reference is opaque � just a 4-byte value that you pass to the other AEW_* 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 an error(usually an access violation) occurred while trying to access the buffer pointed to by Host.
• 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 writes data and one that checks status.

AEW_Disconnect()

AEW_Disconnect() disconnects a client reference, closing the connection and cleaning up any memory used. After being passed to AEW_Disconnect(), the client reference is invalid.

AEW_SetTimeout()

AEW_SetTimeout() sets the inter-receive timeout for reply 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 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_BAD_LENGTH if TimeoutMS is zero or negative.

AEW_ChangeNetworking()

AEW_ChangeNetworking() changes the device's IP address, subnet mask, and gateway IP address. This change takes effect immediately; the device will close its end of the connection, so on success you should disconnect with AEW_Disconnect(). After a short time you can connect to the new IP with AEW_Connect().

NewIP is the new IP address in dotted decimal string form (like "192.168.1.174").

NewSubnet is the new subnet mask in dotted decimal string form (like "255.255.0.0").

NewGateway is the new gateway IP address in dotted decimal string form (like "192.168.1.1").

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_NOACCESS if an error(usually an access violation) occurred while trying to access the string pointed to by NewIP, NewSubnet, or NewGateway.
• ERROR_INVALID_ADDRESS if one of the strings was not a valid address or address mask.
• ERROR_TIMEOUT if there was a timeout waiting for the reply.
• ERROR_READ_FAULT or ERROR_INVALID_DATA if the reply packet was not interpretable. This may mean the network stream is corrupt; if it persists, disconnect this client ref and call AEW_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 may mean the device needs to be restarted.

AEW_ChangeDeviceIP()

AEW_ChangeDeviceIP() is similar to AEW_ChangeNetworking(), except it only changes the IP address.

AEW_ChangeSubnet()

AEW_ChangeSubnet() is similar to AEW_ChangeNetworking(), except it only changes the subnet mask.

AEW_ChangeGateway()

AEW_ChangeGateway() is similar to AEW_ChangeNetworking(), except it only changes the gateway IP address.

AEW_GetStatus()

AEW_GetStatus() reads the device's status block.

pStatusBytes 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 number of status bytes read.

pStatus 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 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_BAD_LENGTH if the variable pointed to by pStatusBytes is zero or negative.
• ERROR_NOACCESS if an error(usually an access violation) occurred while trying to access the buffer pointed to by pStatus.
• ERROR_TIMEOUT if there was a timeout waiting for the reply.
• ERROR_READ_FAULT or ERROR_INVALID_DATA if the reply packet was not interpretable. This may mean the network stream is corrupt; if it persists, disconnect this client ref and call AEW_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 may mean the device needs to be restarted.

AEW_DEF_Configure() (v1.6 firmware only)

AEW_DEF_Configure writes a digital I/O configuration into nonvolatile memory that gets asserted on subsequent resets/boots

pIOConfigBytes is a pointer to a variable that holds the size of the IOConfig buffer ("7" bytes).

pIOConfig is a pointer to the IOConfig structure / buffer. As a byte buffer the first byte, "buf[0]", holds the input/output configuration for the device's I/O Groups ("ports"). Set bits for input mode, clear bits for output mode. Buf[1..6] hold the data that will be output on any ports configured as outputs (writes to inputs are ignored).

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 AEW_Connect() to get a new one.)
• ERROR_BAD_LENGTH if the variable pointed to by pIOConfigBytes 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 packet was not interpretable. This may mean the network stream is corrupt; if it persists, disconnect this client ref and call AEW_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 may mean the device needs to be restarted.

AEW_DEF_GetIOConfig() (v1.6 firmware only)

AEW_DEF_GetIOConfig reads the current digital I/O configuration as well as the configuration stored in nonvolatile memory that gets asserted on subsequent resets/boots (as configured with AEW_DEF_Configure()

pIOConfigBytes is a pointer to a variable that holds the size of the IOConfig buffer ("14" bytes). On return, this variable will be set to the number of bytes read.

pIOConfig is a pointer to the IOConfig structures / buffer that will hold the two I/O Configuration structures. As a byte buffer the first byte, "buf[0]", holds the current input/output configuration for the device's I/O Groups ("ports"). Set bits for input mode, clear bits for output mode. Buf[1..6] hold the current data seen on all bits. Buf[7] holds the Power On Default I/O settings, and buf[8..14] hold the Power On Default output port data.

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 AEW_Connect() to get a new one.)
• ERROR_BAD_LENGTH if the variable pointed to by pIOConfigBytes 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 packet was not interpretable. This may mean the network stream is corrupt; if it persists, disconnect this client ref and call AEW_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 may mean the device needs to be restarted.

AEW_DIO_Configure()

AEW_DIO_Configure() sets the direction of the DIO bytes, writes to all of them, and then disables the tristate. Writes to input bytes are ignored.

pDataBytes is a pointer to a variable that holds the size of the data buffer to write from, in bytes. On return, this variable will be set to the amount of data written. For the ETH-DIO-48, the variable should always be 6.

pData is a pointer to the data buffer to write from.

pDirection is a pointer to the direction buffer. This is one byte long per 8 data bytes or fraction. For the ETH-DIO-48, direction should always be 1 byte long. If bit 0 is set, DIO byte 0 becomes an input, otherwise it becomes an output; and so on for each additional DIO byte. For the ETH-DIO-48, a direction buffer of 3F is all inputs, a direction buffer of 00 is all outputs.

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_BAD_LENGTH if the variable pointed to by pDataBytes is zero or negative.
• ERROR_NOACCESS if an error(usually an access violation) occurred while trying to access a buffer pointed to by pData or pDirection.
• ERROR_TIMEOUT if there was a timeout waiting for the reply.
• ERROR_READ_FAULT or ERROR_INVALID_DATA if the reply packet was not interpretable. This may mean the network stream is corrupt; if it persists, disconnect this client ref and call AEW_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 may mean the device needs to be restarted.

AEW_DIO_WriteAll()

AEW_DIO_WriteAll() writes to all the DIO.

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. For the ETH-DIO-48, the variable should always be 6.

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 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_BAD_LENGTH if the variable pointed to by pDataBytes is zero or negative.
• ERROR_NOACCESS if an error(usually an access violation) occurred while trying to access the buffer pointed to by pData.
• ERROR_TIMEOUT if there was a timeout waiting for the reply.
• ERROR_READ_FAULT or ERROR_INVALID_DATA if the reply packet was not interpretable. This may mean the network stream is corrupt; if it persists, disconnect this client ref and call AEW_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 may mean the device needs to be restarted.

AEW_DIO_Write1()

AEW_DIO_Write1() writes to one bit of DIO.

BitIndex is which bit to write to. For the ETH-DIO-48, this is from 0 to 47.

bNewValue is the state of the bit to write; nonzero will set the bit, zero will clear the bit.

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_TIMEOUT if there was a timeout waiting for the reply.
• ERROR_READ_FAULT or ERROR_INVALID_DATA if the reply packet was not interpretable. This may mean the network stream is corrupt; if it persists, disconnect this client ref and call AEW_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 may mean the device needs to be restarted.

AEW_DIO_ReadAll()

AEW_DIO_ReadAll() reads from all the DIO.

pDataBytes is a pointer to a variable that holds the size of the buffer to read to, in bytes. On return, this variable will be set to the amount of data read. For the ETH-DIO-48, the variable should always be 6.

pData is a pointer to the buffer to read to.

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_BAD_LENGTH if the variable pointed to by pDataBytes is zero or negative.
• ERROR_NOACCESS if an error(usually an access violation) occurred while trying to access the buffer pointed to by pData.
• ERROR_TIMEOUT if there was a timeout waiting for the reply.
• ERROR_READ_FAULT or ERROR_INVALID_DATA if the reply packet was not interpretable. This may mean the network stream is corrupt; if it persists, disconnect this client ref and call AEW_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 may mean the device needs to be restarted.

struct {
    unsigned char op[4];       //0 ~ 3
    unsigned char ver[2];      //4 ~ 5
    unsigned char mac[6];      //6 ~ 11
    unsigned char ip[4];       //12 ~ 15
    unsigned char subnet[4];   //16 ~ 19
    unsigned char gw[4];       //20 ~ 23
    unsigned char dhcp;        //24
    unsigned char myMac[6];    //25 ~ 30
    unsigned char pad;
}

struct {
    unsigned char Ins;     // 6 bits, one per I/O Group ("port"): set for input, clear for output
    unsigned char Data[6]; // the 48 bits of data to configure the output levels (ignored for I/O Groups configured as inputs)
} IOConfig

struct {
  byte Data[6]; // DI values after write has occurred
  byte PriorData[6]; // DI values before write occurred
}