Library For Interacting with a Deta.sh Base Instance Using an Arduino-Based ESP32
Here is a 2 part tutorial that uses this library to send and receive static(fixed minified JSON strings) and dynamic data(such as values from a sensor): https://github.com/A223D/ESP32DetaGuides
This library is abstracts away the networking aspect of interacting with a Deta.sh Base Instance, a free online NoSQL data base. This library uses Deta's provided HTTP API, and exposes all functions listed there. It is meant to be used on an ESP32 running the Arduino core provided by Espressif.
- Deta Project ID
- Deta Project key (aka API Key)
- Deta Base name
The Deta Project ID and Project Key are created when you a make new Deta project. Please note that the Project Key is displayed only once. So make sure to note it down. The Deta Base name is set when a new Base instance is created. Read the provided docs to get started.
- Wifi Connection (using the inbuilt WiFi.h library)
Please note that enterprise connections are not accepted. The best way to experiment is using a mobile hotspot created with a phone or laptop.
A result
struct is internally defined in the following manner:
typedef struct {
int statusCode;
String reply;
} result;
All functions that interact with Deta return a result
structure containing the status code of the response received from the server, as well as the reply. The reply is not the complete response text, bu just the payload of the complete response in JSON. This payload along with the status describes either the success or failure of a request(or function) along with the reason. The Deta Base HTTP API docs describe all the types of requests and their possible responses. In addition to the docs, here is a list of all HTTP status codes and their meanings.
The strings being passed to each function all correspond to the payload required by each HTTP request given in the docs. Consequently, they must be in the same format mentioned. They can however be one-line objects instead of the multi-line format. **Make sure each "
has a preceding \
to make it an escape character.
DetaBaseObject(WiFiClientSecure wifiObject, char* detaID, char* detaBaseName, char* apiKey);
- Creates
DetaBaseObject
on which functions below can be called. Takes aWiFiClientSecure
object, which does not need anything done to it. You can just declare aWiFiClientSecure
object and then pass it here. Requires a Deta project ID, Deta Base name, and Deta Project Key/API Key. It also allocated memory for a base URI (described in the docs), creates, and assigns it to an internal variable.
- Creates
DetaBaseObject(WiFiClientSecure wifiObject, char* detaID, char* detaBaseName, char* apiKey, bool debugOption);
- Same as previous, but enables debugging statements if
true
is passed for thedebugOption
parameter.
- Same as previous, but enables debugging statements if
Each function exposed corresponds to a request listed in the docs.
result putObject(char* jsonObject);
jsonObject
must be in the same format as described in the Base HTTP docs, i.e.{"items":[{"key":{key},"field1":"value1"}]}
with key being optional. In a C++ string though, a\
character must be added before each"
, but the resulting\"
is counted as 1 character. Hence thejsonObject
becomes{\"items\":[{\"key\":{key},\"field1\":\"value1\"}]}
. The key, if provided, must also be a string. Otherwise it is automatically assigned by Deta and is returned with the full object in thereply
in the returnedresult
object. You can also put another JSON object in the value of an item.
result getObject(char* key);
- This request does not require a JSON payload, but only a key.
key
can be a valid or invalid key in the database, and the status code will reflect that.reply
will contain either the full object with the key provided or an error.
- This request does not require a JSON payload, but only a key.
result deleteObject(char* key);
- Similar to
getObject
, this does not require a JSON payload, but only a valid or invalid key. The status code returned will always be200(successful)
and the reply will contain the key provided originally. By design, there is no way to know if an entry with thatkey
existed, or if the key was invalid.
- Similar to
result insertObject(char* jsonObject);
- Similar to
getObject
, but with slightly different payload/jsonObject
format. According to the docs, the"items"
key does not require an array, but just an object to be created in the database, with an optional key. When a key is provided, an entry is only created if there no other entry with the same key. If a key is not provided, it is the same asputObject
.
- Similar to
result updateObject(char* jsonObject, char* key)
;- Updates an entry only if an entry with that
key
exists according to the payloadjsonObject
. See here to understand the format of the payload/jsonObject
required with an example.
- Updates an entry only if an entry with that
result query(char* queryObject);
char* getDetaID();
- Simply returns Deta ID provided.
char* getBaseURI();
getBaseURI()
returns a character array in the following format:/v1/{project_id}/{base_name}
~DetaBaseObject();
- The destructor just frees the the memory allocated to hold the Base URI.
void printResult(result resultObject);
- This method just prints the status code and JSON payload received in the response to a request(or function call) with a
\n
character in the end. The\n
character is added by this function for convenience and is not present in thereply
of the returnedresult
struct.
- This method just prints the status code and JSON payload received in the response to a request(or function call) with a
Examples are provided for reference and can be accessed though the Arduino menu or through the examples
directory in this repository.
WiFiClientSecure client;
DetaBaseObject detaObj(client, detaID, detaBaseName, apiKey, true);
A WiFiClientSecure
object is needed to initialize a DetaBaseObject
object, and must be passed to it. There is no needed modification to the WiFiClientSecure
object.
A WiFi connection must be established using the inbuilt WiFi
library like so:
WiFiClientSecure client;
DetaBaseObject detaObj(client, detaID, detaBaseName, apiKey, true);
void setup() {
Serial.begin(115200);
WiFi.begin("SSID", "PASSWORD");
Serial.println("Waiting to connect to WiFi");
while (WiFi.status() != WL_CONNECTED) {
delay(500);
Serial.print(".");
}
Serial.println();
digitalWrite(LED, HIGH);
}
void loop(){
//do something here with detaObj
}