MiniApache

"HTTP server library"

This library allows Arduino with ethernet shield to handle HTTP requests. Library gives user simple tools to write custom, dynamic webpages and serves files directly from SD card. MiniApache is designed to make Arduino a part of Internet of Things.

Navigation

Examples

Hello world!

  1. #include <Ethernet.h>
  2. #include <MiniApache.h>
  3.  
  4. byte mac[] = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 }; // MAC address from Ethernet shield sticker under board
  5. IPAddress ip(192, 168, 0, 179); // IP address, may need to be changed depending on network
  6. MiniApache apache(80); // Create a server at port 80 - default for http
  7.  
  8. void setup(){
  9.     Serial.begin(9600); // Serial for debugging
  10.     pinMode(10, OUTPUT);
  11.     digitalWrite(10, HIGH); // Disable Ethernet chip
  12.     Ethernet.begin(mac, ip);  // Initialize Ethernet device
  13.     apache.begin("/served", 4); // Initialize MiniApache server: served path and SD card pin
  14. }
  15.  
  16. void loop() {
  17.     apache.PendingRequest();
  18.     apache.ProcessRequest();
  19. }
  20.  
Change mac to MAC address from Ethernet shield sticker under board. On SD card create directory served and file within it named index.htm, containing Hello World!. After opening in browser address 192.168.0.179 you should see Hello World!. Just by editing contents of created directory (served) user can change displayed web pages. It's caused by design of MiniApache library which serves all files in given directory (/served).

Listing directory

Extend previous example by modifying file tree to:

  • served
    • index.htm
    • data
      • 1.txt
      • 2.txt

After opening in browser address 192.168.0.179 you should still see contents of index.htm. List of files in served/data/ will be displayed under address 192.168.0.179/data/.

Custom view

  1. #include <Ethernet.h>
  2. #include <MiniApache.h>
  3.  
  4. byte mac[] = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}; // MAC address from Ethernet shield sticker under board
  5. IPAddress ip(192, 168, 0, 179); // IP address, may need to be changed depending on network
  6. MiniApache apache(80); // Create a server at port 80
  7.  
  8. void setup(){
  9.     Serial.begin(9600); // Serial for debugging
  10.     pinMode(10, OUTPUT);
  11.     digitalWrite(10, HIGH); // Disable Ethernet chip
  12.     Ethernet.begin(mac, ip);  // Initialize Ethernet device
  13.     apache.begin("/served", 4); // Initialize MiniApache server: served path and SD card pin
  14. }
  15.  
  16. void loop() {
  17.   if(apache.PendingRequest()){ // Check for pending request
  18.     if (apache.RequestIs("/test")){ // Check if request path is equal to /test
  19.       apache.PrintHeader(); // Start response
  20.       // equivalent to PrintHeader(200, "OK", "text/html", false); - 200 (OK) response of text/html type, not cached
  21.       apache.client.print("Test succesfull"); // Write response
  22.       apache.ReportClientServed(); // Finish response
  23.     }
  24.   }
  25.   apache.ProcessRequest();
  26. }
Change mac to MAC address from Ethernet shield sticker under board. Create directory served on SD card and file index.htm within it with any content. After opening in browser address 192.168.0.179/test you should see Test succesfull. When your browser sends request and arduino receives it, function apache.PendingRequest() returns true. You can check request path with function apache.RequestIs("/path_to_check"). If it returns true, you should handle request. Handling requests consists of 3 phases: writing headers, writing content and closing response. Writing headers is implemented by function apache.PrintHeader(). Writing content is done by calling apache.client.print("...content..."). Closing response is implemented by function apache.ReportClientServed(). Calling it is very important because server will be locked until response is finished.

For advanced usage, in MiniApache.h, check out:

  • Default arguments of functions: PrintHeader, ReportClientServed.
  • Functions: RequestStartsWith, QuickResponse.

Error handling

  1. #include <Ethernet.h>
  2. #include <MiniApache.h>
  3.  
  4. byte mac[] = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 }; // MAC address from Ethernet shield sticker under board
  5. IPAddress ip(192, 168, 0, 179); // IP address, may need to be changed depending on network
  6. MiniApache apache(80); // Create a server at port 80
  7.  
  8. void setup(){
  9.     Serial.begin(9600); // Serial for debugging
  10.     pinMode(10, OUTPUT);
  11.     digitalWrite(10, HIGH); // Disable Ethernet chip
  12.     Ethernet.begin(mac, ip);  // Initialize Ethernet device
  13.     apache.begin("/served", 4); // Initialize MiniApache server: served path and SD card pin
  14. }
  15.  
  16. void loop() {
  17.   if(apache.PendingRequest()){ // Check for pending request
  18.     if (apache.RequestIs("/error")){ // Check if request path is equal to /test
  19.       apache.PrintHeader(); // Start response
  20.       apache.client.print("Error state set"); // Write response
  21.       apache.ReportClientServed(); // Finish response
  22.       apache.SetError(100); // Set server in error state
  23.     }
  24.   }
  25.   apache.ProcessRequest();
  26. }
Change mac to MAC address from Ethernet shield sticker under board. Create directory served on SD card and file index.htm within it with any content. At this point server will function normally. After opening in browser address 192.168.0.179/error you should see Error state set. After that, server will no longer handle requests. Instead, on any request it will display error message containing given code and corresponding message. For custom errors, high (>100) codes are advised.

MiniApache can automatically detect and report errors:

  • 1SD card initialization failed!
  • 2Can't find index file! Check SD card and reset device.
  • 3Ethernet module initialization failed!

GET Data

  1. #include <Ethernet.h>
  2. #include <MiniApache.h>
  3.  
  4. byte mac[] = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 }; // MAC address from Ethernet shield sticker under board
  5. IPAddress ip(192, 168, 0, 179); // IP address, may need to be changed depending on network
  6. MiniApache apache(80); // Create a server at port 80
  7.  
  8. void setup(){
  9.     Serial.begin(9600); // Serial for debugging
  10.     pinMode(10, OUTPUT);
  11.     digitalWrite(10, HIGH); // Disable Ethernet chip
  12.     Ethernet.begin(mac, ip);  // Initialize Ethernet device
  13.     apache.begin("/served", 4); // Initialize MiniApache server: served path and SD card pin
  14. }
  15.  
  16. void loop() {
  17.   if(apache.PendingRequest()){ // Check for pending request
  18.     if (apache.RequestIs("/get_data")){ // Check if request path is equal to /get_data
  19.       apache.PrintHeader(); // Start response
  20.       if (apache.GETVariableIs("password", "admin")){ // Check if GET variable named "password" is equal to "admin"
  21.         apache.client.print("My secret pie recipe:<br>..."); // Tell my secrets
  22.       } else {
  23.         apache.client.print("Nothing here :)"); // Not telling
  24.       }
  25.       apache.ReportClientServed(); // Finish response
  26.     }
  27.   }
  28.   apache.ProcessRequest();
  29. }
Change mac to MAC address from Ethernet shield sticker under board. Create directory served on SD card and file index.htm within it with any content. After opening in browser address 192.168.0.179/get_data you should see Nothing here :). But after opening in 192.168.0.179/get_data?password=admin you should see My secret pie recipe: .... This mechanism can be used to exchange date between browser and Arduino.

For advanced usage, in MiniApache.h, check out:

  • Function: GetGETVariable.
  • Memory handling in body of function GETVariableIs.

Share