Arduino HTTP Client Library

Accessing HTTP Servers with Arduino HTTPClient Library

About HTTPClient

HTTPClient is a Arduino Library to easily post normal HTTP Requests using the Arduino Ethernet Shield (a WiFly Version is on the way). Instead of manually implementing the HTTP protocol for each and every web page you want to read from or post to you can simply use the HTTP Client library.

HTTPClient was implemented as memory aware as possible. E.g. all default HTTP information is directly read from flash memory to save up precious RAM.

Getting HTTP Client

You can download the latest version of HTTP Client from GitHub. Unzip it in your  Arduino Libraries Folder and include ‘HTTPClient.h’ in your Arduino sketch. Arduino.cc has some description how to do this.

If you encounter any problems there is an issue system on GitHub were you can post your issues.

Creating a HTTP Client

HTTP Client works with the Arduino Ethernet Library. Before you can create a HTTP client you must initialize your ethernet connection with something like:

Ethernet.begin(mac, ip);

For details on this see Server.begin() for the Arduino Ethernet Library.
To create a client (in this example for pachube) you can simply call one of
the constructors:

// The address of the server you want to connect to (pachube.com):
byte server[] = { 173,203,98,29 };
HTTPClient client("api.pachube.com",server);

which is equivalent to

HTTPClient client("api.pachube.com",server,80);

Now you are ready to go.

Posting request

HTTP client supports three types of requests:

  • normal GET request to get some data from a URL.
  • POST requests to transfer bigger amount of data to a server.
  • PUT request as used by REST APIs.
  • currently there is no need for DELETE requests – so they do not exist yet. But this wil change as soon as this kind of requests is needed.

Reading the Response Data

The result of a request is a stream (aka FILE*) by that you can read the data without the need to keep the whole answer in memory – which would fail for most HTML pages. FILE* streams are a bit more unusual the normal Arduino streams. They have been  choosen since you can use all the nice fprintff and fscanf routines of avr-libc.
After reading the response from the stream it has to be closed with the method

closeStream(stream)

Do not forget it! Each stream has some data attached and if you forget to close the stream you get a memory leak, slowly filling up the precious memory of the Arduino.
The result code of a HTTP request can be read with getLastReturnCode(). It returns a integer containing the return code. 200 indicates that everything was ok. For further details of HTTP return codes refer to RFC2616 Section 10.
The HTTPClient has also a debug mode which can be witched on and off by using debug() with parameter 0 as no debug and anything else ? e.g. -1 ? as enabling debug output.
By default the debug code is disabled. If debug is enabled the complete request and response is printed out on the serial connection. Very useful if your request do not work.

Passing Additional Parameters

All request take a number of parameters (depending on the request type):

  • The URI – a string (char*) containing the uri – which is normally everything following the hostname of a URL for http://arduino.cc/en/Reference/HomePage it would be /Reference/HomePage.
  • Optional parameters as key value pairs. Parameters are appended to a URL like http://myhost/the/uri?parameter-name=parameter-value&other=parameter parameters are values of the struct http_client_parameter. It is easiest to do this like

    http_client_parameter parameters[] = {
    { "key","afad32216dd2aa83c768ce51eef041d69a90a6737b2187dada3bb301e4c48841" }
    ,{ NULL,NULL }
    };
  • For POST and PUT request a string with additional data can be passed as a string. The data has to be in memory. Future Versions may have future features.
  • For all requests additional headers can be specified. It works exactly the same was as uri parameters:

    http_client_parameter pachube_api_header[] = {
    { "X-PachubeApiKey","afad32216dd2aa83c768ce51eef041d69a90a6737b2187dada3bb301e4c48841" }
    ,{ NULL,NULL }
    };

{ 14 comments… read them below or add one }

jorge orengo June 13, 2011 at 22:55

Dear,
I wonder if you made ??the script I receive the posts of the arduino? I plan on doing with PHP and JSON, but if you did something to receive the data please help me posting the code.

Best Regards,

JORGE ORENGO

Reply

Marcus June 14, 2011 at 06:25

No. The Arduino lib is just for the Arduino. On the server side you can handle it with PHP, Django, Rails, Java or whatever.
The Arduino can be adapted to the server protocol. So there is no need for a specific server adaption.

Reply

Dietmar June 16, 2011 at 20:00

Hi

I’ve tried this code inside loop() and it is called very 10s:

if ( tenSecs ) {
FILE* result = client.getURI(“/test/P.php”,get_parms);
if (result!=NULL) {
int returnCode = client.getLastReturnCode();
if (returnCode==200) {
Serial.println(“loop::data uploaded”);
}
else {
Serial.print(“ERROR: Server returned “);
Serial.println(returnCode);
}
client.closeStream(result);
}
else {
Serial.println(“ERROR::failed to connect”);
}
}

Only the first GET works. All others fail – any idea?

//Dietmar

Reply

Mikkel September 4, 2011 at 23:28

I’m having a similar issue. The first request seems to work, but on subsequent requests I’m only getting the first line of the header.

e.g. I’m contacting a django server, with debugging enabled the first response I get looks like this
—————————————
HTTP/1.0 200 OK
Date: Sun, 04 Sep 2011 21:21:42 GMT
Server: WSGIServer/0.1 Python/2.7.2
Content-Type: text/html; charset=utf-8

((response body))
—————————————
And subsequent responses are simply:
HTTP/1.0 200 OK

So I’m not even getting the entire header. I’m pretty sure the problem is not server-side.

Reply

Mikkel September 5, 2011 at 00:12

Also, I seem to be getting some very strange numbers from getLastReturnCode(). The debugging prints show status 200, but getLastReturnCode is giving me varying numbers, even negative numbers:
1300
513
2
512
-236
1024
etc.. There seems to be no fixed pattern

Marcus September 5, 2011 at 09:16

I have created an issue over at github. I will look into this ASAP.
If you encoutner ither problems, please open an issue over at github, simplifies the process for me a bit.
Thanks

Martin August 22, 2011 at 15:29

Hi, does your HTTPClient library support the Wifly now? What are the dependencies and instructions to set it up with Wifly?

Martin

Reply

Marcus August 22, 2011 at 15:40

Hi,

no, yes, unsure. ;)

In the network of the HTTP Client Library you can see that there is a WiFly branch which is quite up to date to the ‘normal’ branch: https://github.com/interactive-matter/HTTPClient/network

I have done some test with the Wifly shield some time ago. By that time the library/driver for the wifly shield was very buggy – so I did not use it very much. So in theory it should work as expected – there are only some small changes in the way the library talks to the network module.

So check it out and tell me your experiences.

Thanks

Marcus

Reply

João Costa January 29, 2012 at 21:21

How can I post data to a page? I see the function but there is no relevant examples of it. Can you please give me a simple example where i can simply post a number. I have a solution with a simple get request, but what i really intent is a post request.

Reply

Marcus January 29, 2012 at 21:49

I must admit I do not know it right now. I think you can give a byte array with the post content. If I remember correctly it was needed to give a proper data size.
Hope it helps but I will try to come up with an example.

Reply

Brian February 7, 2013 at 00:37

I would love more example as well.

ram May 23, 2012 at 10:08

Dear,
how to get the data which is sent by the commons.httpclient.HttpClient by using BytearrayRequestEntity in the server

I mean what is code to get that data in client side.

Reply

Chris Bautista June 28, 2013 at 11:21

Hi

I was wondering if one can use the HTTPClient Library to do a file upload using an HTTP PUT. I have a working audio shield system recording audio I want this files uploaded to a server. Existing ftp code doesnt work on WIFI so Im trying a different route. Already setup a PUT handler on my server. Just not having any success with a HTTP put from scratch on arduino.

Thanks

Chris

Reply

Marcus September 5, 2011 at 09:17

Leave a Comment