OpENer - Open Source EtherNet/IP(TM) I/O Target Stack  2.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Porting OpENer

OpENer configuration setup.

General Stack Configuration

The general stack properties have to be defined prior to building your production. This is done by providing a file called opener_user_conf.h. An example file can be found in the src/ports/POSIX or src/ports/WIN32 directory. The documentation of the example file for the necessary configuration options: opener_user_conf.h

This file contains the general application specific configuration for OpENer.

Furthermore you have to specific platform specific network include files. OpENer needs definitions for the following data-types and functions:

  • struct sockaddr_in
  • AF_INET
  • INADDR_ANY
  • htons
  • ntohl
  • inet_addr

Startup Sequence

During startup of your EtherNet/IP(TM) device the following steps have to be performed:

  1. Configure the network properties:
    With the following functions the network interface of OpENer is configured:
    • EIP_STATUS ConfigureNetworkInterface(const char *ip_address, const char *subnet_mask, const char *gateway_address)
    • void ConfigureMACAddress(const EIP_UINT8 *mac_address)
    • void ConfigureDomainName(const char *domain_name)
    • void ConfigureHostName(const char *host_name)
    Depending on your platform these data can come from a configuration file or from operating system functions. If these values should be setable remotely via explicit messages the SetAttributeSingle functions of the EtherNetLink and the TCPIPInterface object have to be adapted.
  2. Set the device's serial number
    According to the CIP specification a device vendor has to ensure that each of its devices has a unique 32Bit device id. You can set it with the function:
    • void setDeviceSerialNumber(EIP_UINT32 serial_number)
  3. Initialize OpENer:
    With the function CipStackInit(EIP_UINT16 unique_connection_id) the internal data structures of opener are correctly setup. After this step own CIP objects and Assembly objects instances may be created. For your convenience we provide the call-back function ApplicationInitialization. This call back function is called when the stack is ready to receive application specific CIP objects.
  4. Create Application Specific CIP Objects:
    Within the call-back function ApplicationInitialization(void) or after CipStackInit(void) has finished you may create and configure any CIP object or Assembly object instances. See the module OpENer User interface for available functions. Currently no functions are available to remove any created objects or instances. This is planned for future versions.
  5. Setup the listening TCP and UDP port:
    THE ETHERNET/IP SPECIFICATION demands from devices to listen to TCP connections and UDP datagrams on the port AF12hex for explicit messages. Therefore before going into normal operation you need to configure your network library so that TCP and UDP messages on this port will be received and can be hand over to the Ethernet encapsulation layer.

Normal Operation

During normal operation the following tasks have to be done by the platform specific code:

  • Establish connections requested on TCP port AF12hex
  • Receive explicit message data on connected TCP sockets and the UPD socket for port AF12hex. The received data has to be hand over to Ethernet encapsulation layer with the functions:
    int HandleReceivedExplictTCPData(int socket_handle, EIP_UINT8* buffer, int buffer_length, int *number_of_remaining_bytes),
    int HandleReceivedExplictUDPData(int socket_handle, struct sockaddr_in from_address, EIP_UINT8 buffer, unsigned int buffer_length, int *number_of_remaining_bytes).
    Depending if the data has been received from a TCP or from a UDP socket. As a result of this function a response may have to be sent. The data to be sent is in the given buffer pa_buf.
  • Create UDP sending and receiving sockets for implicit connected messages
    OpENer will use to call-back function int CreateUdpSocket( UdpCommuncationDirection connection_direction, struct sockaddr_in *pa_pstAddr) for informing the platform specific code that a new connection is established and new sockets are necessary
  • Receive implicit connected data on a receiving UDP socket
    The received data has to be hand over to the Connection Manager Object with the function EIP_STATUS HandleReceivedConnectedData(EIP_UINT8 *data, int data_length)
  • Close UDP and TCP sockets:
    1. Requested by OpENer through the call back function: void CloseSocket(int socket_handle)
    2. For TCP connection when the peer closed the connection OpENer needs to be informed to clean up internal data structures. This is done with the function void CloseSession(int socket_handle).
  • Cyclically update the connection status:
    In order that OpENer can determine when to produce new data on connections or that a connection timed out every kOpenerTimerTickInMilliSeconds milliseconds the function EIP_STATUS ManageConnections(void) has to be called.

Callback Functions

In order to make OpENer more platform independent and in order to inform the application on certain state changes and actions within the stack a set of call-back functions is provided. These call-back functions are declared in the file opener_api.h and have to be implemented by the application specific code. An overview and explanation of OpENer's call-back API may be found in the module Callback Functions Demanded by OpENer.