README.md

RestClient for Arduino

HTTP Request library for Arduino and the Ethernet shield.

Install

Clone (or download and unzip) the repository to ~/Documents/Arduino/libraries where ~/Documents/Arduino is your sketchbook directory.

> cd ~/Documents/Arduino
> mkdir libraries
> cd libraries
> git clone https://github.com/csquared/arduino-restclient.git RestClient

Usage

Include

You need to have the Ethernet library already included.

#include <Ethernet.h>
#include <SPI.h>
#include "RestClient.h"

RestClient(host/ip, [port])

Constructor to create an RestClient object to make requests against.

Use domain name and default to port 80:

RestClient client = RestClient("arduino-http-lib-test.herokuapp.com");

Use a local IP and an explicit port:

RestClient client = RestClient("192.168.1.50",5000);

dhcp()

Sets up EthernetClient with a mac address of DEADBEEFFEED. Returns true or false to indicate if setting up DHCP was successful or not

  client.dhcp()

Note: you can have multiple RestClient objects but only need to call this once.

Note: if you have multiple Arduinos on the same network, you'll need to give each one a different mac address.

begin(byte mac[])

It just wraps the EthernetClient call to begin and DHCPs. Use this if you need to explicitly set the mac address.

  byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
  if (client.begin(mac) == 0) {
     Serial.println("Failed to configure Ethernet using DHCP");
  }

Manual Ethernet Setup

You can skip the above methods and just configure the EthernetClient yourself:

  byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
  //the IP address for the shield:
  byte ip[] = { 192, 168, 2, 11 };
  Ethernet.begin(mac,ip);

  byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
  Ethernet.begin(mac);

This is especially useful for debugging network connection issues.

RESTful methods

All methods return an HTTP status code or 0 if there was an error.

get(const char* path)

get(const char* path, String* response)

Start making requests!

int statusCode = client.get("/"));

Pass in a string by reference for the response:

String response = "";
int statusCode = client.get("/", &response);

post(const char* path, const char* body)

post(const char* path, String* response)

post(const char* path, const char* body, String* response)

String response = "";
int statusCode = client.post("/", &response);
statusCode = client.post("/", "foo=bar");
response = "";
statusCode = client.post("/", "foo=bar", &response);

put(const char* path, const char* body)

put(const char* path, String* response)

put(const char* path, const char* body, String* response)

String response = "";
int statusCode = client.put("/", &response);
statusCode = client.put("/", "foo=bar");
response = "";
statusCode = client.put("/", "foo=bar", &response);

del(const char* path)

del(const char* path, const char* body)

del(const char* path, String* response)

del(const char* path, const char* body, String* response)

String response = "";
int statusCode = client.del("/", &response);

Full Example

I test every way of calling the library (against a public heroku app)[https://github.com/csquared/arduino-http-test].

You can find the file in File->Examples->RestClient->full_test_suite

Debug Mode

If you're having trouble, you can always open RestClient.cpp and throw at the top:

#define HTTP_DEBUG

Everything happening in the client will get printed to the Serial port.

Thanks

ricardochimal For all his c++ help. Couldn't have done this without you!

theycallmeswift Helping incept and debug v1.0