Ethernet Client

This library creates a client which can connect to a specified internet IP address and port in an Ethernet.

EthernetClient()

Description

Constructor to create a client.

Syntax (Example)

EthernetClient client

Parameters

None

connected

Description

Whether or not the client is connected.

Syntax

int8_t client.connected()

Parameters

None

Returns

Returns true if the client is connected, false if not connected.

connect

Description

Connects to the server.

Syntax

int connect(IPAddress ip, uint16_t port)
int connect(URL, uint16_t port)

Parameters

ip: The IP address that the client will connect to (array of 4 bytes)
URL: The domain name the client will connect to (string, ex.:"arduino.cc")
port: The port that the client will connect to (uint16_t)

Returns

Returns an int (1, -1, -2, -3, -4) indicating connection status:
  SUCCESS 1
  TIMED_OUT -1
  INVALID_SERVER -2
  TRUNCATED -3
  INVALID_RESPONSE -4

write

Description

Write data to the server the client is connected to. This data is sent as a byte or series of bytes.

Syntax

client.write(val)
client.write(buf, len)

Parameters

val: A value to send as a single byte (byte or char)
buf: An array to send as a series of bytes (byte or char)
len: The length of the buffer

Returns

Byte
write() returns the number of bytes written. It is not necessary to read this value.

print

Description

Print data to the server that a client is connected to. Prints numbers as a sequence of digits, each an ASCII character (e.g. the number 123 is sent as the three characters '1', '2', '3').

Syntax

client.print(data)
client.print(data, BASE)

Parameters

data: The data to print (char, byte, int, long, or string)
BASE (optional): The base in which to print numbers: DEC for decimal (base 10), OCT for octal (base 8), HEX for hexadecimal (base 16).

Returns

Byte: Returns the number of bytes written, though reading that number is optional.

println

Description

Print data, followed by a carriage return and newline, to the server a client is connected to. Prints numbers as a sequence of digits, each an ASCII character (e.g. the number 123 is sent as the three characters '1', '2', '3').

Syntax

client.println()
client.println(data)
client.print(data, BASE)

Parameters

data: The data to print (char, byte, int, long, or string)
BASE (optional): The base in which to print numbers: DEC for decimal (base 10), OCT for octal (base 8), HEX for hexadecimal (base 16).

Returns

Byte: Returns the number of bytes written, though reading that number is optional.

available

Description

Returns the number of bytes available for reading (that is, the amount of data that has been written to the client by the server it is connected to).

Syntax

int client.available()

Parameters

None

Returns

The number of bytes available.

read

Description

Read the next byte received from the server the client is connected to.

Syntax

int client.read()

Parameters

None

Returns

The next byte (or character), or -1 if none is available.

stop

Description

Disconnect from the server.

Syntax

client.stop()

Parameters

None

Returns

None

flush

Description

Discard any bytes that have been written to the client but not yet read.

Syntax

client.flush()

Parameters

None

Returns

None


Sample Program

Connect with DHCP, and then display the IP address.


        #include <Arduino.h>
        #include <SPI.h>
        #include <Ethernet.h>
         
        // Enter a MAC address for your controller below.
        // Newer Ethernet shields have a MAC address printed on a sticker on the shield
        byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
        // if you don't want to use DNS (and reduce your sketch size)
        // use the numeric IP instead of the name for the server:
        //IPAddress server(74,125,232,128);  // numeric IP for Google (no DNS)
        char server[] = "www.google.com";    // name address for Google (using DNS)
         
        // Set the static IP address to use if the DHCP fails to assign
        IPAddress ip(192,168,0,177);
         
        // Initialize the Ethernet client library
        // with the IP address and port of the server 
        // that you want to connect to (port 80 is default for HTTP):
        EthernetClient client;
         
        void setup() {
         // Open serial communications and wait for port to open:
          Serial.begin(9600);
           while (!Serial) {
            ; // wait for serial port to connect. Needed for Leonardo only
          }
         
          // start the Ethernet connection:
          if (Ethernet.begin() == 0) {
            Serial.println("Failed to configure Ethernet using DHCP");
            // no point in carrying on, so do nothing forevermore:
            // try to configure using IP address instead of DHCP:
            Ethernet.begin(mac, ip);
          }
          // give the Ethernet shield a second to initialize:
          delay(1000);
          Serial.println("connecting...");
         
          // if you get a connection, report back via serial:
          if (client.connect(server, 80)) {
            Serial.println("connected");
            // Make a HTTP request:
            client.println("GET /search?q=arduino HTTP/1.1");
            client.println("Host: www.google.com");
            client.println("Connection: close");
            client.println();
          } 
          else {
            // kf you didn't get a connection to the server:
            Serial.println("connection failed");
          }
        }
         
        void loop()
        {
          // if there are incoming bytes available 
          // from the server, read them and print them:
          if (client.available()) {
            char c = client.read();
            Serial.print(c);
          }
         
          // if the server's disconnected, stop the client:
          if (!client.connected()) {
            Serial.println();
            Serial.println("disconnecting.");
            client.stop();
         
            // do nothing forevermore:
            while(true);
          }
        }