mDash library API reference

This howto documents mDash library API. The library could be used in Arduino IDE or ESP-IDF environments, and it is located at https://github.com/cesanta/mDash.

Initialisation

mDashBegin: initialise mDash library

void mDashBegin(void);

This function should be the first mDash function called in the setup() . It initialised the mDash library. If a device has WiFi and cloud credentials setup (via the Serial provisioning process, or via the API), then The library creates MQTT connection to the mdash.net service and keeps it alive, reconnecting automatically when required.

mDashGetState: get current device state

int mDashGetState(void);

Return device state, which could be one of:

  • MDASH_NO_IP: device has not yet obtained an IP address
  • MDASH_AP_IP: device has started an access point and obtained an IP address
  • MDASH_STA_IP: device has joined WiFi and obtained an IP address
  • MDASH_CONNECTED: device has successfully connected to mDash

mDashGetFreeRam: get free RAM

unsigned long mDashGetFreeRam(void);

Return free RAM in bytes

Configuration

mDashConfigGet: get configuration parameter

int mDashConfigGet(const char *name, char *buf, size_t bufsize);

Get configuration parameter name stored in the mdash.cfg file.

Return value:

  • 0: the config variable name was found and copied into buf
  • -3: the config variable name was not found in mdash.cfg
  • -2: the destination buffer size bufsize is too small to hold the value
  • -1: the cofig file mdash.cfg is absent or could not be opened

mDashConfigSet: set configuration parameter

int mDashConfigSet(const char *name, const char *value);

Set the config variable name to value by saving it to the config file mdash.cfg. If value is NULL or an empty string, the configuration variable is removed from the config file.

Return value:

  • 0: successfully saved
  • -1: error opening config file

Some of the configuration variables are used by the library:

  • wifi.sta.ssid: WiFi network name
  • wifi.sta.pass: WiFi password
  • device.id: registered device ID
  • device.pass: registered device password (token)
  • debug.level: logging level. Default is 2. Use 0 to disable, 3 to verbose

mDashCLI: proccess command input

void mDashCLI(unsigned char input_byte);

Process one input byte (e.g. from Serial or from network) of the configuration command line interface. Commands are separated by a new line. Currently supported commands are:

  • set NAME VALUE - set config variable. Use - value to remove variable
  • reboot - reboot device

The typical usage is to provision device to WiFi and/or cloud. Example:

  // Until connected to the cloud, enable provisioning over serial
  while (mDashGetState() != MDASH_CONNECTED)
    if (Serial.available() > 0) mDashCLI(Serial.read());

MQTT

mDashPublish: MQTT publish

void mDashPublish(const char *topic, const char *fmt, ...);

Parameters:

  • const char *topic - MQTT topic to publish to
  • const char *fmt, ... - a format string with parameters, to form an MQTT message. The syntax is the same as for the mDashReportSuccess() function.

mDashSubscribe: MQTT subscribe

void mDashSubscribe(const char *topic, void (*fn)(const char *, const char *));

Parameters:

  • const char *topic - a topic to subscribe to
  • fn - a callback function that gets called when a message arrives to the subscribed topic. A function receives topic name and a message.

RPC

mDashExport: export custom RPC function

typedef void (*mDashRpcCallback_t)(void *ctx, void *cbdata);
void mDashExport(const char *name, mDashRpcCallback_t cb, void *cbdata);

Export custom RPC function. Parameters:

  • void *ctx - an opaque RPC context pointer, used to get parameters and return result
  • void *cbdata - an arbitrary pointer that is passed to the callback

The callback function can parse parameters, do some logic, and report either success or error. See example at CustomRpcFunction sketch.

mDashReturnSuccess: report RPC success

void mDashReturnSuccess(void *ctx, const char *json_fmt, ...);

Report success. This function creates a successful JSON-RPC response frame {"id": ..., "result": ...}. Parameters:

  • const char json_fmt - a printf-like format string for creating $.result JSON object. It accepts the following specifiers:
    • %Q print quoted escaped string. Expect NUL-terminated char *
    • %.*Q print quoted escaped string. Expect int, char *
    • %s print string as is. Expect NUL-terminated char *
    • %.*s print string as is. Expect int, char *
    • %g print floating point number. Expect double
    • %d/%u print signed/unsigned integer. Expect int
    • %ld/%lu print signed/unsigned long integer. Expect long
    • %B print true or false. Expect int
    • %V print quoted base64-encoded string. Expect int, char *
    • %H print quoted hex-encoded string. Expect int, char *

mDashReturnError: report RPC error

void mDashReturnError(void *ctx, const char *error_message);

Report error. This function creates a error JSON-RPC frame that gets sent to the caller: {"id": ..., "error": {"code": 500, "message": "your_error_message"}}. Parameters:

  • const char *error_message - a error string returned as $.error.message

mDashGetParams: return JSON string containing RPC parameters

const char *mDashGetParams(void *ctx);

Return JSON string which contains RPC function arguments. For example, if the JSON-RPC frame looks like {"id":1,"method":"Sum","params":[1,2]}, then the mDashGetParams() would return [1,2].

mDashGet: get RPC call parameters

int mDashGetNum(const char *s, const char *path, double *val);
int mDashGetStr(const char *s, const char *path, char *to, int len);
int mDashGetBase64(const char *s, const char *path, char *to, int len);
int mDashGetBool(const char *s, const char *path, int *v);

This function gets a value from the JSON string s by the value's JSONPath path. Parameters:

  • const char *s - a JSON string
  • const char *path - a value's JsonPath. For example, if you want to fetch foo from the {"foo": 123}, use $.foo.
  • double *v - a pointer to the fetched value
  • char *to, int len - the buffer for the string value

Return value: 1 if the value was found by path, 0 otherwise.