ClearCore Ethernet

Overview

ClearCore provides fully-featured Ethernet functionality at 10 Mbps and 100 Mbps with a 10Base-T/100Base-TX Ethernet port. The ClearCore package implements LwIP's TCP/IP protocol suite and
provides a user-friendly API for TCP and UDP capabilities.

Wiring and Initialization

• Connect the ClearCore to a router/switch using a standard ethernet RJ45 cable, or directly to another ClearCore or PC using an ethernet cross-over cable. Use the dedicated ClearCore ETHERNET
  port.
• Make sure the router/switch or connected device is on.
• Verify that the Ethernet connector's LED turns on. This is a status indicator for link activity. The Ethernet LED can only indicate one of two states, off or blinking, to indicate the absence
  or prescence of network activity, respectively.
  • If the LED does not come on after connecting an RJ45 cable connected to the network the ClearCore won't be able to communicate on the network.
• Set up Ethernet functionality through the ClearCore EthernetManager.
  • To configure with a static IP address, if manual configuration is required or DHCP is unavailable:

    // Specify the desired network values:
    // ClearCore IP address
    IpAddress ip = IpAddress(192, 168, 1, 8);
    // Router/switch IP address
    IpAddress gateway = IpAddress(192, 168, 1, 1);
    // Mask to separate network vs. host addresses (required for TCP)
    IpAddress netmask = IpAddress(255, 255, 255, 0);
     
    // Set the network values through the EthernetManager.
    EthernetMgr.Setup();
    EthernetMgr.LocalIp(ip);
    EthernetMgr.GatewayIp(gateway);
    EthernetMgr.NetmaskIp(netmask);

  • To configure with an IP address assigned via DHCP:

    EthernetMgr.Setup();
    bool dhcpSuccess = EthernetMgr.DhcpBegin();
    if (dhcpSuccess) {
        // DHCP successfully assigned an IP address.
    }

• To confirm that everything is working properly, once an IP address has been assigned, you should be able to communicate to the ClearCore using the Windows ping command from a PC on the same
  network.
  • Make sure that the sketch running on the ClearCore calls EthernetMgr.Refresh() in a timely manner in the loop() function so that incoming and outgoing packets will get processed. In
    practical applications, this refreshing will be taken care of by the functions that send and receive packets.
  • Connect a PC to the router/switch that the ClearCore is connected to.
  • On that PC, open a Windows cmd shell, type "ping <ClearCore_IP_address>", and hit Enter. You should see four lines that begin with "Reply from <ClearCore_IP_address>: bytes=32", indicating
    that the ClearCore is online.
  • If instead you see "Reply from <ClearCore_IP_address>: Destination host unreachable", or if the ping otherwise fails, make sure the router/switch is on, the correct IP address was supplied
    to ping, and that the ClearCore is running a sketch that called EthernetMgr.Setup(), successfully configured an IP address, and calls EthernetMgr.Refresh() at a reasonable rate.

Ethernet TCP

The TCP functionality of the ClearCore provides a Client-Server interface, allowing the ClearCore to act as either a client or a server. TCP is connection-oriented and provides built-in error
checking, guaranteed packet delivery, and delivery of packets in order. TCP is best suited for an application where reliability is more valuable than speed.

TCP Client

From the Client-Server perspective, the client of a TCP connection is the device who initiates the connection.

• To initialize the ClearCore as a client connecting to a remote server:

  EthernetTcpClient client;
  IpAddress serverIp = IpAddress(192, 168, 1, 78);
  // Start a TCP connection with the server on port 8888.
  if (client.Connect(serverIp, 8888)) {
      // Successfully connected to the server.
  }

  Note

  Ethernet functionality must be initialized before initializing TCP communications.

• To communicate with the connected server:
  • Incoming TCP packets from the server are automatically buffered within the client. To process received data, the client's buffer can be read-from directly at any time by calling
    EthernetTcpClient::Read().
  • Outgoing TCP packets are automatically created and sent when using the EthernetTcpClient::Send() API. The TCP protocol of acknowledging received packets and resending lost packets is
    handled automatically.

TCP Server

From the Client-Server perspective, the server of a TCP connection is the device that listens for and accepts incoming connection requests. The EthernetTcpServer interface provides two distinct options for managing connected clients. Choose one or the other, but do not mix usage of EthernetTcpServer::Available() and EthernetTcpServer::Accept().

Automatic Client Management (recommended)

    - To obtain a reference to a connected client while leaving management of that client up to the server, use EthernetTcpServer::Available()
  - Each client reference is an EthernetTcpClient object. 
    - Incoming TCP packets from an individual client are automatically buffered within the client. To process received data, the client's buffer can be read-from directly at any time by

calling EthernetTcpClient::Read().

• Outgoing TCP packets to an individual client are automatically created and sent when using the EthernetTcpClient::Send() API. The TCP protocol of acknowledging received packets and resending lost packets is handled automatically.
• Outgoing TCP packets may be sent through the server to all currently connected clients using EthernetTcpServer::Send(). (applicable only when using the server’s automatic Client management).

// Initialize the ClearCore as a server listening for incoming client connections
  EthernetTcpServer server = EthernetTcpServer(8888);
  // Start listening for TCP connections on port 8888.
  server.Begin();

// Obtain a reference to a connected client with incoming data                              available.
        EthernetTcpClient client = server.Available();
        if (client.Connected()) {
// The server has returned a connected client with incoming data available.
           while (client.BytesAvailable() > 0) {
    // Send the data received from the client over a serial port.
               ConnectorCOM0.Send(client.Read());
           }
        }

Manual Client Management

• To obtain a reference to a connected client and stop it from being managed by the server, use EthernetTcpServer::Accept().
  • Each client reference is an EthernetTcpClient object.
    • Incoming TCP packets from an individual client are automatically buffered within the client. To process received data, the client's buffer can be read-from directly at any time by
      calling EthernetTcpClient::Read().
    • Outgoing TCP packets to an individual client are automatically created and sent when using the EthernetTcpClient::Send() API. The TCP protocol of acknowledging received packets and
      resending lost packets is handled automatically.

      // Initialize the ClearCore as a server listening for incoming client connections
        EthernetTcpServer server = EthernetTcpServer(8888);
        // Start listening for TCP connections on port 8888.
        server.Begin();

          \code{.cpp}
          // The server will no longer keep track of connected clients returned by Accept().
          EthernetTcpClient clients[4];
          clients[0] = server.Accept();
          if (clients[0].Connected()) {
              // Send a TCP packet to the client with a payload containing the string.
              clients[0].Send("Hello World");
          }
          \endcode                
      

Ethernet UDP

UDP communications are connectionless and do not provide error checking or guaranteed delivery. The EthernetUdp interface manages a local UDP session and provides methods for sending and receiving
UDP datagrams. UDP is best suited for an application that performs its own error checking and appropriately handles packet loss or an application that requires efficiency and speed.

• UDP Initialization
  • To initialize a local UDP session:

    // Start a local UDP session on port 23.
    EthernetUdp Udp;
    Udp.Begin(23);

    Note

    Ethernet functionality must be initialized before initializing UDP.

    An EthernetUdp instance is bound to a local port upon initialization. Providing a local port number of 0 will bind to a random local port.

• UDP Communication
  • To send a UDP datagram to a remote destination:

    // Form a new packet addressed to a specified remote IP address and port.
    IpAddress remoteIp = IpAddress(192, 168, 1, 78);
    uint16_t remotePort = 8888;
    // Set up to send a packet to a remote IP/port.
    Udp.Connect(remoteIp, remotePort);
    // Write data into the payload of the outgoing packet.
    Udp.PacketWrite("Hello World.");
    // Send the packet to the remote destination.
    Udp.PacketSend();

  • To process a received UDP datagram.

    // Save the newest UDP packet to be read from.
    uint16_t packetSize = Udp.PacketParse();
    // Read the contents of the received packet into our own variable.
    char[packetSize] packetContents;
    Udp.PacketRead(packetContents, packetSize);