Offers an easy to set up REST server to control the ESP8266 module. Includes a DNS capturing WiFi AP configuration portal.
PREi is built on top of the ESP8266 Arduino Core, so that's an obvious dependency. Refer to this link for instructions on how to install it.
Another dependency (which might be removed in future versions) is on PREi NTP, used for displaying the real time on the configuration portal.
One of the best things about PREi is its ease of installation and compatibility with both Arduino and PlatformIO!
- Clone or download this project as well as PREi NTP
- Open the Arduino IDE, go to Sketch -> Include Library -> Add .ZIP Library...
- Select the PREi NTP library first, then repeat for the PREi library as well
- Upon a successful installation, an example project can be found by navigating to File -> Examples -> PREi -> myApp
- Go to the Libraries tab on the PlatformIO Home page.
- Search and find the PREi library and click the Install button
- Choose to install the library only for the current project (recommended) or globally
As you can see from the example project included, all you have to do is include the library's header, instantiate a PREi object and call its run method every loop.
#include <PREi.h> // Include the library
PREi *r; // Define a new PREi variable
void setup() {
r = new PREi("ESP8266", "abcdef12"); // Instantiate it with an SSID and password (optionally)
}
void loop() {
r->run(); // Call its run method every loop
}Both constructor parameters are optional, if the password is not included, the WiFi AP will be open and if the SSID is not included either, the SSID will be chosen as follows :
"ESP_" + String(ESP.getChipId())Note that the SSID also dictates the mDNS hostname for the device.
Once connected to the ESP's wireless network, the configuration portal will pop up as a hotspot login page. It can also be accessed from the root page of the ESP.
For the configuration portal, the ESP is simply trying to access the index.html file on its SPIFFS. For simple usage it is recommended you use the PREi Config Portal.
The portal allows for a simple way to connect the ESP to a local wireless network, displaying scanned WiFis sorted by strength. It also shows some other useful information about the module.
Pins can be controlled via pseudo-REST requests* to the pin/pin-name endpoints. The pin name can be any from D0 to D8 for the digital pins, or A0 for the analog input.
A GET request returns a JSON with the pin's state that looks like this:
{
"data": {
"name": "D4",
"pin": 2,
"digital": true,
"mode": "input", // output / pwm
"value": 1 // 0 - 1023 (0V - 3,3V) for PWM mode
}
}A PUT request with the mode parameter set to any of output, input or pwm changes the pin into that mode.
A POST request will put the pin in a HIGH power state (3,3V). The request can also contain the val parameter set to any value from 0 to 1023 to change that pin's PWM value, if the pin is in the PWM mode.
A DELETE request will put the pin in a LOW power state (0V).
Most digital sensors function at a much higher speed than HTTP can provide, so sending data packets via POST/DELETE sequences is out of discussion. For such cases, PREi uses callback functions or pointers to return the necesarry information or to control complex peripherals.
Using the addSensor method, by specifing a sensor name and a callback function or a pointer, you can implement complex behaviour that can be triggered by making a GET request to /sensor/{sensorName}. The JSON's "message" value will be the value returned by the callback function, or the value from the pointed address.
An example for getting the temperature and humidity using an DHT22 and Adafruit's DHT sensor library.
#include <PREi.h>
#include <DHT.h>
PREi *r;
DHT dht(2, DHT22);
float getTemperature() {
return dht.readTemperature();
}
float getHumidity() {
return dht.readHumidity();
}
void setup() {
dht.begin();
r = new PREi("ESP8266", "abcdef12");
r->addSensor("temperature", getTemperature); // accessed at /sensor/temperature
r->addSensor("humidty", getHumidity); // accessed at /sensor/humidity
}
void loop() {
r->run();
}The PREi interface also exposes some minimal hardware control to the pseudo-REST API.
The ESP module has it's URI set as /esp.
A GET request will return a huge JSON containing all the information presented on the configuration portal as well.
A POST request containing a URL for the firmware parameter will prompt the ESP to query that URL for a new firmware update. In case the query comes back with a 200 response, the ESP will start a OTA update.
A DELETE request will attempt restart the ESP module. Due to a known issue with the ESP8266 a power-cycle after the initial serial flash is required to ensure the software reset will work properly.
The ESP's WiFi has it's URI set as /wifi.
A GET request will start a WiFi scan and return a JSON containing a list of nearby WiFis with their SSID, RSSI and encryption type.
A POST request will make the ESP attempt to connect to the wireless specified by the ssid parameter, optionally using the password specified in the pass parameter.
A DELETE request will make the ESP disconnect from the wireless network, if connected to any.