Skip to main content

HTTPS POST request

What this example shows​

Connect to your Wi-Fi network and send a JSON POST request over HTTPS every 10 seconds, then print the status code and the reply in the Serial Monitor. The sketch posts to JSONPlaceholder, a fake API for testing: you get a reply like a real API gives, but nothing is stored. A real API usually needs an API key and more parameters. The sketch uses HTTPS without checking the server's certificate. For a request that checks a certificate, see HTTPS with a certificate.

Before you upload, write your network name and password between the quotes of ssid and pass. Open the Serial Monitor at 115200 baud to see what happens.

Example code​

Select Board
Inkplate7SPECTRA_HTTPS_POST_Request.ino
// Include needed libraries
#include "Inkplate.h"
#include "ArduinoJson.h"
#include "HTTPClient.h"
#include "WiFi.h"
#include <WiFiClientSecure.h>

// Enter your WiFi credentials
const char *ssid = "";
const char *pass = "";

// Specify the API URL to send a POST request
const char *apiUrl = "https://jsonplaceholder.typicode.com/posts";

// Specify the delay time between 2 POST requests in milliseconds
#define DELAY_BETWEEN_REQUESTS 10000

// Create objects from included libraries
WiFiClientSecure client;
HTTPClient http;
Inkplate display; 

void setup()
{
    // Init serial communication
    Serial.begin(115200);

    // Init the display
    display.begin();
    
    // Connect to WiFi
    WiFi.begin(ssid, pass);
    Serial.println("Connecting to WiFi");
    while (WiFi.status() != WL_CONNECTED)
    {
        Serial.print(".");
        delay(500);
    }
    Serial.println();
    Serial.print("Connected to WiFi with IP address ");
    Serial.println(WiFi.localIP());

    // Use https but don't use a certificate
    client.setInsecure();
}

void loop()
{
    // Init HTTP client with secure wifi client and the API URL
    http.begin(client, apiUrl);

    // Add header. In your case maybe you must add more depending on your API
    http.addHeader("Content-Type", "application/json");

    // Create a JSON document for serializing data
    const size_t CAPACITY = JSON_OBJECT_SIZE(1);
    StaticJsonDocument<CAPACITY> doc;

    // Convert the JSON document to a JSON object in order to add data
    JsonObject object = doc.to<JsonObject>();

    // Add data in the JSON object
    object["title"] = "Hello Inkplate";

    // Serialize the JSON object with your data to a JSON document for sending
    char jsonOutput[128];
    serializeJson(doc, jsonOutput);

    // Send the POST request and save returned code
    int httpCode = http.POST(String(jsonOutput));

    // If the code is smaller than 0, something went wrong
    if (httpCode > 0)
    {
        // Get the string returned by the HTTPS request and print the response
        String payload = http.getString();
        Serial.println("Status code: " + String(httpCode));
        Serial.println(payload);

        // End connection
        http.end();
    }
    else
    {
        Serial.println("Error on HTTPS request");
    }

    // Wait for sending next request
    delay(DELAY_BETWEEN_REQUESTS);
}

This example also uses WiFi, HTTPClient and WiFiClientSecure (arduino-esp32), which come with the ESP32 board package and are not part of the Inkplate library. It also uses ArduinoJson (arduinojson.org), which is not part of the Inkplate library either. Their functions below are described as the sketch uses them.

Functions used​

Inkplate()returns None

Creates the Inkplate object. Inkplate 7SPECTRA has a single six-color mode, so the constructor takes no mode argument.

ReturnsConstructor; no return value.

display.begin()returns void

Initializes the library, the peripherals and the frame buffer. Call it once in setup().

ReturnsNothing.

Serial.begin(unsigned long baud)returns void

Starts serial communication at the given baud rate, here 115200.

ReturnsNothing.

Serial.print(value)returns size_t

Prints text to the Serial Monitor without a new line.

ReturnsNumber of bytes printed.

Serial.println(value)returns size_t

Prints text followed by a new line to the Serial Monitor.

ReturnsNumber of bytes printed.

WiFi.begin(const char *ssid, const char *pass)returns wl_status_t

Starts connecting to the Wi-Fi network.

ReturnsThe connection status.

WiFi.status()returns wl_status_t

Returns the connection status. The sketch waits until it is WL_CONNECTED.

ReturnsThe connection status.

WiFi.localIP()returns IPAddress

Returns the IP address the board got on the network.

ReturnsThe board's IP address.

WiFiClientSecurereturns None

Wi-Fi client class for HTTPS connections. The sketch creates one object, client, and passes it to the HTTP client.

ReturnsType; no return value.

HTTPClientreturns None

HTTP client class. The sketch creates one object, http, and uses it to send the POST request.

ReturnsType; no return value.

JsonObjectreturns None

ArduinoJson type for a JSON object. The sketch gets one from the document and adds the key title to it.

ReturnsType; no return value.

WiFiClientSecure.setInsecure()returns void

Makes the client use HTTPS without checking the server's certificate.

ReturnsNothing.

HTTPClient.begin(WiFiClient &client, String url)returns bool

Starts a request to the address through the given client, here the secure client and the JSONPlaceholder address.

Returnstrue if the request could be started.

HTTPClient.addHeader(const String &name, const String &value)returns void

Adds a header to the request. The sketch sets Content-Type to application/json.

ReturnsNothing.

StaticJsonDocumentreturns None

ArduinoJson document with a fixed memory size, here JSON_OBJECT_SIZE(1), room for one key and value.

ReturnsType; no return value.

doc.to()returns JsonObject

ArduinoJson function that turns the document into an empty JSON object you can add data to. The sketch adds the key title with the value Hello Inkplate.

ReturnsThe JSON object.

serializeJson(doc, char *output)returns size_t

ArduinoJson function that writes the document as JSON text into the buffer.

ReturnsNumber of bytes written.

HTTPClient.POST(String payload)returns int

Sends the text as the body of a POST request.

ReturnsThe HTTP status code, or a negative number on an error.

HTTPClient.getString()returns String

Returns the body of the reply as text.

ReturnsThe reply body.

HTTPClient.end()returns void

Ends the request and frees its resources.

ReturnsNothing.

delay(unsigned long ms)returns void

Waits the given number of milliseconds: 500 between the connection dots and 10000 between requests.

ReturnsNothing.

What to expect​

The Serial Monitor shows the connection progress, then every 10 seconds the status code and the reply of the server. The screen is not used.

Serial MonitorAutoscrollShow timestampNewline115200 baud
Message (Enter to send message to the board)
Connecting to WiFi

This line is followed by one dot every half second until the board is connected, then Connected to WiFi with IP address and the board's address. After that, each request prints Status code: with the HTTP status code the server answered, then the reply body.

If the request fails, the sketch prints Error on HTTPS request instead.

🔗Open the complete example

examples/Inkplate7SPECTRA/Advanced/WEB_WiFi/Inkplate7SPECTRA_HTTPS_POST_Request

→