Skip to content

Latest commit

 

History

History
573 lines (570 loc) · 22.6 KB

API.md

File metadata and controls

573 lines (570 loc) · 22.6 KB
Raw

API

Note: when you get a value using api like get, hget, etc. please keep in mind to free memory each time using the free api.

To prevent memory leak, code like this must be avoided:

//Do not use
Arancino.set("test", Arancino.get("mem"));

Use the following instead:

//Use this
char* mem = Arancino.get("mem");
Arancino.set("test", mem);
Arancino.free(mem);

is possible in some application static memory reserved for ArancinoPacket is not enough. To change the value of the memory assignment edit the follow line in ArancinoDefinition.h:

//MsgPack
#define CMD_DOC_SIZE 512  //size for the message sent from the MCU
#define RSP_DOC_SIZE 256  // size for message received on the MCU

Currently the memory values ​​is sized to work with FreeRTOS enabled, if FreeRTOS is disabled is possible to increase these values.

metadata

void metadata(ArancinoMetadata data) | DEPRECATED from Version 1.4.0

Stores the metadata to use later during the START command in begin API.

Parameters
  • data: struct of type ArancinoMetadata. Represents the firmware name, version and local timezone offset.
Example
#include <Arancino.h>
ArancinoMetadata amdata = {
 .fwname = "Arancino Firmware",
 .fwversion = "1.0.0",
 .tzoffset = "+1000"
};
void setup() {
 // deprecated: do not use the .metadata function directly. Use the mandatory metadata argument in the begin function instead.
 // This will be removed in the next major relase
 //Arancino.metadata(meta);
 //
 Arancino.begin(amdata);
}
void loop() {
 // Do something
}

attachInterface

void attachInterface(ArancinoIface& iface) ***

Sets an ArancinoIface to be used by the Arancino Protocol as communication medium.

Parameters
  • iface: class of type ArancinoIface. Represent the medium that will be used by the protocol in order to communicate with an Arancino Module.
Example
#include <Arancino.h>
//Interface for Arancino protocol
SerialIface iface;

void setup() {

  //Please remember to provide a serial port when not using an Arancino board
  //iface.setSerialPort(Serial);
  iface.setSerialPort();
  Arancino.attachInterface(iface);
  Arancino.begin(amdata);
}

begin

void begin(ArancinoMetadata amdata, bool useid = false, int timeout = TIMEOUT ) | DEPRECATED from Version 1.4.0
void begin(ArancinoMetadata amdata, ArancinoConfig aconfig)

Starts the communication with the Arancino Module. When communication starts, the begin transmits the Arancino Library version for compatibility evaluatation. From version 1.4.0 the ArancinoMetadata argument became mandatory, becouse the data contained in it is part of the initial trasmission. From version

Parameters
  • ArancinoConfig: is class composed only by attributes (see the following paragraph: Arancino Config):
  • DECIMAL_DIGITS
  • SERIAL_TIMEOUT
  • PORT_ID_PREFIX_KEY The convenience of using class ArancinoConfig is to be able to increase the number of parameters without necessarily having to change the prototypes. The use of the following arguments in the begin function is deprecated and will be removed in the next major release.
  • timeout
  • useid

set

ArancinoPacket set(char* key, char* value [, bool isPersistent] )
ArancinoPacket set(char* key, int value [, bool isPersistent] )
ArancinoPacket set(char* key, float value [, bool isPersistent] )
ArancinoPacket set(char* key, long value, [, bool isPersistent] )
ArancinoPacket set(char* key, uint32_t value, [, bool isPersistent] )

Set key to hold the string value. If key already holds a value, it is overwritten, regardless of its type.

Parameters
  • key: the key name
  • value: the value for the specified key. can be char*, int o float
  • isPersistent optional boolean value to specify if value must be stored persistently or not. Default is false.
Return value

ArancinoPacket reply: ArancinoPacket containing:

  • isError: API call outcome (true or false);
  • responseCode: the response code value.
  • responseType: VOID;
  • response: NULL;
Note: 2, 5

get

char* get(char* key)
ArancinoPacket get<ArancinoPacket>(char* key)

Get the value of key. If the key does not exist, the special value NULL is returned.

Parameters
  • key: the name of the key from which the value is retrieved
Return value

char* reply:

  • string that contains the value of selected key.
  • NULL if the key doesn't exist. or ArancinoPacket reply: ArancinoPacket containing:
  • isError: API call outcome (true or false);
  • responseCode: the response code value.
  • responseType: STRING;
  • response.string: char* pointer that can contain the value of selected key or NULL if the key doesn't exist.
Note: 1, 4

mset

ArancinoPacket mset(char** keys, char** values, uint len)

Executes the MSET command. Every key in the keys parameter is set to the corresponding value in the values parameter.

Parameters
  • keys: keys to set;
  • values: corresponding values of the keys;
  • len: number of keys to set, namely the length of keys array.
Return value

ArancinoPacket reply: ArancinoPacket containing:

  • isError: API call outcome (true or false);
  • responseCode: the response code value.
  • responseType: VOID;
  • response: NULL;
Note: 3

mget

char** mget(char** keys, char** values, uint len)
ArancinoPacket mget<ArancinoPacket>(char** keys, uint len)

Retrieves multiple keys from redis.

Parameters
  • keys: array containing keys to retrieve;
  • len: number of keys to retrieve.
Return value

get function can return both char** and ArancinoPacket depending on the template used.

char**

In this case an array of char* in returned. Every element contains the value stored in the corresponding key in the keys parameter. If a key doesn't exist the corresponding element in the returned array is NULL.

ArancinoPacket

ArancinoPacket reply: ArancinoPacket containing:

  • isError: API call outcome (true or false);
  • responseCode: the response code value.
  • responseType: STRING_ARRAY;
  • response.stringarray: char** pointer that points to the start of the returned array of strings.
Note: 1, 4

del

int del(char* key )
ArancinoPacket del<ArancinoPacket>(char* key )

Removes the specified key. A key is ignored if it does not exist.

Parameters
  • key: the name of the key to delete.
Return value

int reply: The number of keys that were removed. or ArancinoPacket reply: ArancinoPacket containing:

  • isError: API call outcome (true or false);
  • responseCode: the response code value.
  • responseType: INT;
  • response.integer: The number of keys that were removed.
Note: 1

keys

char** keys(char* pattern)
ArancinoPacket keys<ArancinoPacket>(char* pattern)

Returns all the keys matching the pattern. Supported glob-style patterns:

  • h?llo matches hello, hallo and hxllo
  • h*llo matches hllo and heeeello
  • h[ae]llo matches hello and hallo, but not hillo
  • h[^e]llo matches hallo, hbllo, ... but not hello
  • h[a-b]llo matches hallo and hbllo Use \ to escape special characters if you want to match them verbatim.
Parameters
  • pattern: the pattern used to find matching keys.
Return value

char** reply: list of keys matching pattern. or ArancinoPacket reply: ArancinoPacket containing:

  • isError: API call outcome (true or false);
  • responseCode: the response code value.
  • responseType: STRING_ARRAY;
  • response.stringArray: char** pointer to the string array of keys matching pattern.

hset

ArancinoPacket hset(char* key, char* field , char* value )
ArancinoPacket hset(char* key, char* field , int value )
ArancinoPacket hset(char* key, char* field , float value )
ArancinoPacket hset(char* key, char* field , long value )
ArancinoPacket hset(char* key, char* field , uint32_t value )

Sets field in the hash stored at key with the specified value. If key does not exist, a new key holding a hash is created. If field already exists in the hash, it is overwritten.

Parameters
  • key: the name of the key used to create the hash.
  • field: the name of the field to store in the hash.
  • value: the value to store in the hash with the specified field.
Return value

ArancinoPacket reply: ArancinoPacket containing:

  • isError: API call outcome (true or false);
  • responseCode: the response code value.
  • responseType: VOID;
  • response: NULL;
Note: 2

hget

char* hget(char* key, char* field )
ArancinoPacket hgetPacket<ArancinoPacket>(char* key, char* field )

Returns the value associated with field in the hash stored at key.

Parameters
  • key: the name of the key which hold the hash.
  • field: the name of the field from which the value is retrieved
Return value

char* reply:

  • the value if a value is stored in field at key.
  • NULL if there isn't a value stored. or ArancinoPacket reply: ArancinoPacket containing:
  • isError: API call outcome (true or false);
  • responseCode: the response code value.
  • responseType: STRING;
  • response.string: char* pointer that can contain the value if a value is stored in field at key or NULL if there isn't a value stored.
Note: 1, 4

hgetall

char** hgetall(char* key )
ArancinoPacket hgetall<ArancinoPacket>(char* key )

Returns all fields and values of the hash stored at key. In the returned value, every field name is followed by its value.

Parameters
  • key: the name of the key which holds the hash.
Return value

char** reply: string array of field and value matching key. or ArancinoPacket reply: ArancinoPacket containing:

  • isError: API call outcome (true or false);
  • responseCode: the response code value.
  • responseType: STRING_ARRAY;
  • response.stringArray: char** pointer that can contain the string array of field and value matching key
Note: 1, 4

hkeys

char** hkeys( String key )
ArancinoPacket hkeys<ArancinoPacket>( String key )

Returns all field names in the hash stored at key.

Parameters
  • key: the name of the key which holds the hash.
Return value

char** reply: string array of fields matching key. or

Return value

ArancinoPacket reply: ArancinoPacket containing:

  • isError: API call outcome (true or false);
  • responseCode: the response code value.
  • responseType: STRING_ARRAY;
  • response.stringArray: char** pointer to the string array of fields matching key.
Note: 1, 4

hvals

char** hvals(char* key )
ArancinoPacket hvals<ArancinoPacket>(char* key )

Returns all values in the hash stored at key.

Parameters
  • key: the name of the key which holds the hash.
Return value

char** reply: string array of values matching key. or ArancinoPacket reply: ArancinoPacket containing:

  • isError: API call outcome (true or false);
  • responseCode: the response code value.
  • responseType: STRING_ARRAY;
  • response.stringArray: char** pointer to the string array of values matching key.
Note: 1, 4

hdel

int hdel(char* key, char* field )
ArancinoPacket hdel<ArancinoPacket>(char* key, char* field )

Removes the specified field from the hash stored at key. If field is specified and it does not exist within this hash, this command returns 0. If the key does not exist, it is treated as an empty hash and this command returns 0.

Parameters
  • key: the name of the key stored in the hash.
  • field: the name of the field stored in the hash at key to delete.
Return value

int reply:

  • 1 if the field is removed from hash.
  • 0 if the field or the key does not exist in the hash. or ArancinoPacket reply: ArancinoPacket containing:
  • isError: API call outcome (true or false);
  • responseCode: the response code value.
  • responseType: INT;
  • response.integer: 1 if the field is removed from hash or 0 if the field or the key does not exist in the hash.
Note: 1

flush

ArancinoPacket flush()

Delete all the keys.

Return value

ArancinoPacket reply: ArancinoPacket containing:

  • isError: API call outcome (true or false);
  • responseCode: the response code value.
  • responseType: VOID;
  • response: NULL.

publish

ArancinoPacket publish(char* channel, char* message)
ArancinoPacket publish(char* channel, int message)
ArancinoPacket publish(char* channel, float message)
ArancinoPacket publish(char* channel, uint32_t message)
ArancinoPacket publish(char* channel, long message)

Posts a message to the given channel.

Parameters
  • channel: the name of the channel where the message will be sent.
  • message: message to send.
Return value

ArancinoPacket reply: ArancinoPacket containing:

  • isError: API call outcome (true or false);
  • responseCode: the response code value.
  • responseType: INT;
  • response.integer: the number of clients that received the message.

store

ArancinoPacket store(char* key, int value)
ArancinoPacket store(char* key, float value)
ArancinoPacket store(char* key, long value)
ArancinoPacket store(char* key, uint32_t value)
ArancinoPacket store(char* key, int value, char* timestamp)
ArancinoPacket store(char* key, float value, char* timestamp)
ArancinoPacket store(char* key, long value, char* timestamp)
ArancinoPacket store(char* key, uint32_t value, char* timestamp)

Append (or create and append) a new sample to the series specified by key.

Parameters
  • key: key to store.
  • value: the value for the specified key.
  • timestamp: the expicit timestamp for the specified key.
Return value

char* reply: the insertion timestamp. or ArancinoPacket reply: ArancinoPacket containing:

  • isError: API call outcome (true or false);
  • responseCode: the response code value.
  • responseType: STRING;
  • response.string: char* pointer that contain the insertion timestamp to the series.

mstore

ArancinoPacket mstore(char** key, char** value, int len)
Void mstore(char** key, char** value, int len,char* timestamp)

Append new samples to a list of series.

Parameters
  • keys: the list of keys to store.
  • values: corresponding values of the keys;
  • len: number of keys to set, namely the length of keys array.
  • timestamp: the expicit timestamp for the specified set of keys.
Return value
  • char** reply: list of insertion timestamps.
  • Returns nothing (Void) if timestamp prototype is used. (it uses ExecuteCommandFast so it don't require a response from Arancino Daemon). or ArancinoPacket reply: ArancinoPacket containing:
  • isError: API call outcome (true or false);
  • responseCode: the response code value.
  • responseType: STRING_ARRAY;
  • response.stringArray: char** pointer that points to the start of the returned array of insertion timestamps to the series.

storetags

ArancinoPacket storetags(char* key, char** tags, char** value, int len)
Parameters
  • key: the key to store.
  • tags: the list of the tags to store.
  • values: corresponding values of the tags;
  • len: number of tags to set, namely the length of keys array.
Return value

ArancinoPacket reply: ArancinoPacket containing:

  • isError: API call outcome (true or false);
  • responseCode: the response code value.
  • responseType: VOID;
  • response: NULL;

enableDebugMessages

void enableDebugMessages(bool sendViaCommMode)
void enableDebugMessages(Stream& dbgSerial))

Enables the use of debug messages inside the Arancino Library as well as the use of print functions. If a valid Stream is provided, it will be used to prompt debug messages. As an alternative, it can be chosen to prompt debug messages via set command using the reserved key ___MONITOR___ if true is provided as argument. If nothing (or false) is provided instead, the library will try to initialize the default debug serial port (valid only for Arancino Boards).

Example
#include <Arancino.h>
void setup() {
 Arancino.begin();
 Arancino.enableDebugMessages(SerialUSB);
 //Arancino.enableDebugMessages(true);
 //Arancino.enableDebugMessages();
}
void loop() {
 Arancino.print(0,"Hello from Arancino");
 delay(5000); //wait 5 seconds
}

print

void print(char* message)

Prints a debug message. Refer to enableDebugMessages to see how to configure them.

Example
#include <Arancino.h>
void setup() {
 Arancino.begin();
 Arancino.enableDebugMessages();
}
void loop() {
 Arancino.print("Hello from Arancino");
 delay(5000); //wait 5 seconds
}

println

void println(char* message)

Like print but with a trailing new line char.

getArraySize

int getArraySize(char** array)

Return the array string count.

Parameters
  • array: pointer to string array.
Return value

int reply: string count.

Example
#include <Arancino.h>
void setup() {
 Arancino.enableDebugSerial();
 Arancino.begin();
 Arancino.set("exgetarraysize_pressure",1023);
 Arancino.set("exgetarraysize_humidity",67.5);
 Arancino.set("exgetarraysize_temperature",24.4);
}
void loop() {
 char** key = Arancino.keys();
 int count = Arancino.getArraySize(key);
 Arancino.print("Key count: ");
 Arancino.println(count);
 Arancino.free(key);
}

free

void free(char* string)
void free(char** stringArray)
void free(ArancinoPacket packet)

frees the memory used by a char* string, char** array string, or by an ArancinoPacket.

Parameters
  • string: pointer to string.
  • stringArray: pointer to string array.
  • packet: ArancinoPacket variable.
Example
#include <Arancino.h>
void setup() {
 Arancino.begin();
 Arancino.set("exfree_foo", "bar");
 Arancino.set("exfree_qwe", "asd");
 Arancino.set("exfree_pressure",1023);
 Arancino.set("exfree_humidity",67.5);
 Arancino.set("exfree_temperature",24.4);
}
void loop() {
 char* str = Arancino.get("exfree_foo");
 char** key = Arancino.keys();
 ArancinoPacket myPacket = Arancino.getPacket("exfree_ qwe");
 /* user code... */
 Arancino.free(str);
 Arancino.free(key);
 Arancino.free(myPacket);
}
Note: when the free API is used for freeing an ArancinoPacket, the response type (string or string array ) is auto detected.

isValidUTF8

* bool isValidUTF8(char* string) *

Check if the string is valid and correct for the utf-8 standard.

Parameters
  • string: pointer to string.
Example
#include <Arancino.h>
void setup() {
 Arancino.begin();
}
void loop() {
 char* str = "Test";
 if(isValidUTF8(str))
 Arancino.set("key3", str);
}

Notes

  1. When using get-type functions (such as get, hget, mget, hkeys, hvals, hgetall, ...) the Arancino Module first searches the key in the volatile redis db. If it is not found there, the persistent redis db is used.
  2. When using set and hset functions the key has to be unique between both volatile and persistent db. Example: if we want to set a volatile variable named key1, the Arancino Module first checks if key1 exists in the persistent db.
  3. When using mset function the previous check is not executed. Later, when using get function the default redis db is first used (volatile).
  4. When using arrays returned by Arancino Library functions it is important to free them after usage to prevent memory leaks. Example:
char* temp = Arancino.get("test");
Arancino.set("key2", temp);
Arancino.free(temp);

It is not recommended to do as follows:

Arancino.set("key2", Arancino.get("test"));
  1. When using set-type functions, make sure that the value is correctly formatted with utf-8 standard. Is recommended to use the internal function isValidUTF8 before the set to avoid decoding errors on Arancino Module. Example:
char* value="test";
if(isValidUTF8(value))
Arancino.set("key3", value);

getTimestamp

* char* getTimestamp() *

Return timestamp in UNIX millis format.

Return value

char* timestamp: current timestamp.

Example
#include <Arancino.h>
void setup() {
 Arancino.begin();
}
void loop() {
 char* ts = Arancino.getTimestamp();
 Arancino.set("ts", ts);
 delay(2000);
}

getModuleVersion

* char* getModuleVersion() *

Return Arancino Module version.

Return value

char* modVersion: current Module version.

Example
#include <Arancino.h>
void setup() {
 Arancino.begin();
}
void loop() {
 char* modVers = Arancino.getModuleVersion();
 Arancino.set("mod_version", modVers);
 Arancino.free(modVers);
 delay(2000);
}

getModuleLogLevel

* char* getModuleLogLevel() *

Return current Arancino Module log level.

Return value

char* modVersion: current Module log level.

Example
#include <Arancino.h>
void setup() {
 Arancino.begin();
}
void loop() {
 char* logLvl = Arancino.getModuleLogLevel();
 Arancino.set("Log_level", logLvl);
 Arancino.free(logLvl);
 delay(2000);
}