Renesas Electronics Corporation
Search

Ethernet Client

Basic Library

Digital I/O
Analog I/O
Advanced I/O
Time
Math
Trigonometry
Random Numbers
Bits and Bytes
Interrupts
Serial Comm.

Standard Library

Ethernet
Ethernet (Server)
Ethernet (Client)
Servo Motor
Stepping Motor
Character LCD
EEPROM
SPI
I2C (Wire)
SD
SD (File Operations)
Image Processing
Periodic Operation
Clock (RTC)
Utility

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 (i.e. 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 (i.e. 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 <Ethernet.h>
 
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(216,58,211,3);  // 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.available()) {
    ; // wait for serial port to connect. Needed for Leonardo only
  }
 
  // start the Ethernet connection:
  if (Ethernet.begin(mac) == 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);
  }
}