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 TLS connection to the mdash.net service and keeps it alive, reconnecting automatically when required.

mDashStart: initialise, hardcode cloud credentials

void mDashStart(const char *device_id, const char *device_password);

An alternative to mDashBegin() which hardcodes mDash cloud credentials. The user of this API needs to setup WiFi elsewhere, and and call mDashStart() when a device acquires IP address.

mDashStartWithWifi: initialise, hardcode WiFi and cloud credentials

void mDashStartWithWifi(const char *wifi_name, const char *wifi_password,
        const char *device_id, const char *device_password);

An alternative to mDashBegin() which hardcodes WiFi and mDash credentials.

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.pass: registered device password (token)
  • device.public_key: access token for the external customers
  • 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
  • ll LEVEL - set log level, LEVEL is a number from 0 (no log) to 3 (debug)
  • 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());

RPC - handle remote commands

Reporting data

mDashShadowUpdate: update device shadow

int mDashShadowUpdate(const char *json_format, ...);

Update device shadow.

Example: report free RAM to the shadow

  mDashShadowUpdate("{%Q:{%Q:{%Q:%d}}}",
                    "state", "reported", "RAM", mDashGetFreeRam());

Return value: 1 if the update was sent, 0 if not (e.g. because a network is down).

mDashNotify: send arbitrary notification

int mDashNotify(const char *name, const char *json_format, ...);

Send notification name to mDash. Return value: 1 if the update was sent, 0 if not (e.g. because a network is down).

Events

mDashRegisterEventHandler: register an event handler

enum {
  // Events defined by the mDash library
  MDASH_EVENT_NETWORK_LOST = 0,       // event_data: NULL
  MDASH_EVENT_NETWORK_AP = 1,         // event_data: NULL
  MDASH_EVENT_NETWORK_CONNECTED = 2,  // event_data: NULL
  MDASH_EVENT_CLOUD_CONNECTED = 3,    // event_data: NULL

  // Events defined by user
  MDASH_EVENT_USER = 100,           // Starting number for user-based events
};
typedef void (*evh_t)(void *event_data, void *userdata);
void mDashRegisterEventHandler(int event, evh_t fn, void *userdata);

Register an event handler. Events are used for the asynchronous notification. Some events are triggered by the mDash library. User code can also trigger custom events - for that, event numbers higher than MDASH_EVENT_USER must be used.

Each event has an associated void * pointer which carries an event-specific data, or NULL.

mDashTriggerEvent: trigger an event

int mDashTriggerEvent(int event, void *event_data);

Trigger an event. This function calls all registered event handlers synchronously, passing event_data to them.

Return a number of invoked handlers.

Utility

mDashGetState: get current device state

int mDashGetState(void);

Return current device connection state, one of MDASH_EVENT_* values.

mDashGetFreeRam: get free RAM

unsigned long mDashGetFreeRam(void);

Return free RAM in bytes

mDashGetSdkVersion: get ESP-IDF version

const char *mDashGetSdkVersion(void);

Return ESP-IDF version used to build mDash library.

mDashSetLogLevel: set serial debug level

void mDashSetLogLevel(int logLevel);

Set serial debug level. The default is 2. Acceptable levels are:

  • 0 : no debug logs
  • 1 : only critical messages
  • 2 : critical and info messages (default)
  • 3 : critical, info and debug messages