C/C++ library modules for the Arduino

Follows the API for the modules linkup.cpp and ntptime.cpp that implement the Linkup interface protocol written for the Arduino.

linkup.cpp/linkup.h:

void connectAP(const char* ssid, const char* password, char* reply)

connects to the existing access point (hotspot, router) with ssid and password. reply returns the received dotted IP address; empty if login fails
void createAP(const char* ssid, const char* password)
creates an access point with ssid and password. If password is empty, the AP is open, i.e. you can log in without authentication
void httpGet(const char* url, char* reply) executes an HTTP GET request and returns the response. url in the form "http://<server>?key=value&key=value&...". https can also be used instead of http
void httpPost(const char* url, const char* content, char* reply) executes an HTTP POST request and returns the response. url in the form "http://<server>". content in the format "key=value&key=value&...". https can also be used instead of http
void httpDelete(const char* url) executes an HTTP DELETE request with the given resource
void startHTTPServer(void * onRequest)

starts an HTTP server (web server on port 80) that listens to HTTP GET requests. For a GET request, the user-defined callback function void onRequest(const char* clientIP, const char* filename, const char* params, char* response) is called.

clientIP: dotted IP address of the client
filename: filename of the URL with the prefix "/". Missing the filename: "/".
params: dictionary with the GET Request parameters {key: value}.

Example: For the URL http://192.168.0.101/on?a=ok&b=3:

filename = "/on" and params = {"a"" : "ok", "b" : "3"}

Return in response:

- a string with no starting [ and ending ]. This is returned unchanged to the browser. It can be an HTML web page or a single value. The webpage must not be longer than 250 characters

- a string starting with [ and ending with ] and comma separated key:value pairs. The values contained therein are inserted into the % format specifications of the HTML standard file previously saved with saveHTML() and returned to the browser

- nothing: The HTML text file previously saved with saveHTML() is returned unchanged to the browser

All HTTP replies are provided with a header 200 OK.

The call is blocking. Only the callback function handler is active

void terminateHTTPServer()
sends a command to the ESP32 to unblock a running HTTP server, so it returns in the listening mode
void saveHTML(const char* line)
saves one line of text on the LinkUp in a standard HTML file. It can contain % format specifications, which are replaced with the return values of the callback function handler. The file is closed by sending a empty line
void string_info(const char* s)
Serial.print() information about the string (text, length, ASCII characters)
void terminate() terminates the program by invoking while (true);
void getVersion(char* reply)
reply returns the current library version
void deepsleep()
sets the ESP32 in deep sleep mode
void getNtpTimeRaw(const char* server, char* reply)

reply returns the current date_time delivered by the given server. Format string with colon separated values of yyyy, mm, dd, h, m, s, week_day, day_of_year. Time is GMT.

If server is emtpy, the url pool.ntp.org is used

void mqtt_broker(const char* host, int port, const char* user, const char* password, int keepalive)

determines the properties of the broker (IP address, IP port and if necessary authentication details). keepalive determines how long the connection remains open without data exchange (in sec) (default depends on the broker). No connection to the broker is established yet.

Default values for most brokers: port = 1883, user = "", password = "", keepalive = 0

bool mqtt_connect(bool cleanSession) connects to the broker. For cleanSession = true, all previous data will be deleted. Returns True if the connection has been established; otherwise false
bool mqtt_ping()
sends a ping request to the server to keep the connection open. Returns true if successful; otherwise false

bool mqtt_publish(const char* topic, const char* payload, bool retain, int qos)

 

sends a message for the given topic (payload). If retain = true, this message is regarded as the last good/retain message. qos is the Quality of Service level (only 0, 1 supported). Returns true if successful; otherwise false

Default values for most applications: retain = false, qos = 0

bool mqtt_subscribe(const char* topic, int qos)
subscribes the given topic with the given qos level (only 0, 1 supported). A maximum of 50 receiving message tuples (topic, payload) are stored one after the other in a message buffer (maximum lengths topic: 50, payload: 200 bytes). Returns true if successful; otherwise false
bool mqtt_receive(char* token, char* payload)
retrieves topic and payload of the first element of the message buffer (the "oldest") and removes it from the buffer. If there is no data in the buffer, token and payload are empty. The poll period should be at least 1 sec. Returns false, if the connection to the broker is lost
void mqtt_disconnect() closes the connection


ntptime.cpp/ntptime.h
:

time_t getNtpTime(const char* server)

invokes getNtpTimeRaw(server, reply) and returns the the current time as time_t (unsigned long) (Unix timestamp (epoch): seconds after 1.1.1970). See:

# import <TimeLib.h>

time_t t = getNtpTime("pool.ntp.org");
Serial.println(hour(t));

getNtpTime function pointer be used to call setSyncProvider() to synchronize a time element from TimeLib. In this case, the server pool.ntp.org is used. See:

# import <TimeLib.h>

setSyncProvider(getNtpTime);
time_t t = now();
Serial.println(hour(t));