SoftAP HTTP pages

Note:

SoftAP is available only on the Photon and P1 (Gen 2).

It is not available on cellular devices, the Argon (Gen 3 Wi-Fi), the Photon 2, or P2.

Since 0.5.0:

When the device is in listening mode, it creates a temporary access point (AP) and a HTTP server on port 80. The HTTP server is used to configure the Wi-Fi access points the device attempts to connect to. As well as the system providing HTTP URLs, applications can add their own pages to the SoftAP HTTP server.

SoftAP HTTP Pages is presently an advanced feature, requiring moderate C++ knowledge. To begin using the feature:

  • add #include "Particle.h" below that, then
  • add #include "softap_http.h" below that still
// SYNTAX

void myPages(const char* url, ResponseCallback* cb, void* cbArg, Reader* body, Writer* result, void* reserved);

STARTUP(softap_set_application_page_handler(myPages, nullptr));

The softap_set_application_page_handler is set during startup. When the system is in setup mode (listening mode, blinking dark blue), and a request is made for an unknown URL, the system calls the page handler function provided by the application (here, myPages.)

The page handler function is called whenever an unknown URL is requested. It is called with these parameters:

  • url: the path of the file requested by the client. It doesn't include the server name or port. Examples: /index, /someimage.jpg.
  • cb: a response callback - this is used by the application to indicate the type of HTTP response, such as 200 (OK) or 404 (not found). More on this below.
  • cbArg: data that should be passed as the first parameter to the callback function cb.
  • body: a reader object that the page handler uses to retrieve the HTTP request body
  • result: a writer object that the page handler uses to write the HTTP response body
  • reserved: reserved for future expansion. Will be equal to nullptr and can be ignored.

The application MUST call the page callback function cb to provide a response for the requested page. If the requested page url isn't recognized by the application, then a 404 response should be sent, as described below.