Added Docs for Rainmaker

Author: sanketwadekar

docs/source/api/rainmaker.rst

@@ -1,3 +1,672 @@
-#########
-RainMaker
-#########
+#############
+ESP Rainmaker
+#############
+
+About
+-----
+
+This library allows to work with ESP RainMaker.
+
+ESP RainMaker is an end-to-end solution offered by Espressif to enable remote control and monitoring for ESP32-S2 and ESP32 based products without any configuration required in the Cloud. The primary components of this solution are:
+
+- Claiming Service (to get the Cloud connectivity credentials)
+- RainMaker library (i.e. this library, to develop the firmware)
+- RainMaker Cloud (backend, offering remote connectivity)
+- RainMaker Phone App/CLI (Client utilities for remote access)
+
+The key features of ESP RainMaker are:
+
+1. Ability to define own devices and parameters, of any type, in the firmware.
+2. Zero configuration required on the Cloud.
+3. Phone apps that dynamically render the UI as per the device information.
+
+Additional information about ESP RainMaker can be found `here <https://rainmaker.espressif.com/>`__.
+
+#########################
+Arduino ESP Rainmaker API
+#########################
+
+
+ESP RainMaker Agent API
+-----------------------
+
+
+RMaker.initNode
+***************
+
+This initializes the ESP RainMaker agent, wifi and creates the node.
+
+You can also set the configuration of the node using the following API
+
+``RMaker.setTimeSync(bool val)``
+
+**NOTE**: If you want to set the configuration for the node then these configuration API must be called before `RMaker.initNode()`.
+
+.. code-block:: arduino
+
+    Node initNode(const char *name, const char *type);
+
+* ``name`` Name of the node
+* ``type`` Type of the node
+
+This function will return object of Node.
+
+
+RMaker.start
+************
+
+It starts the ESP RainMaker agent.
+
+**NOTE**:
+
+1. ESP RainMaker agent should be initialized before this call.
+2. Once ESP RainMaker agent starts, compulsorily call WiFi.beginProvision() API.
+
+.. code-block:: arduino
+
+    esp_err_t start();
+
+This function will return `ESP_OK` on success or  `Error` in case of failure.
+
+
+RMaker.stop
+***********
+
+It stops the ESP RainMaker agent which was started using `RMaker.start()`.
+
+.. code-block:: arduino
+
+    esp_err_t stop()
+
+This function will return
+
+1. `ESP_OK` : On success
+2. Error in case of failure.
+
+
+RMaker.deinitNode
+*****************
+
+It deinitializes the ESP RainMaker agent and the node created using `RMaker.initNode()`.
+
+
+.. code-block:: arduino
+
+    esp_err_t deinitNode(Node node)
+
+* ``node`` : Node object created using `RMaker.initNode()`
+
+This function will return
+
+1. `ESP_OK` : On success
+2. Error in case of failure
+
+
+RMaker.enableOTA
+****************
+
+It enables OTA as per the ESP RainMaker Specification. For more details refer ESP RainMaker documentation. check `here <https://rainmaker.espressif.com/docs/ota.html>`__.
+
+.. code-block:: arduino
+
+    esp_err_t enableOTA(ota_type_t type);
+
+* ``type`` : The OTA workflow type.
+    - OTA_USING_PARAMS
+    - OTA_USING_TOPICS
+
+This function will return
+
+1. `ESP_OK` : On success
+2. Error in case of failure
+
+
+RMaker.enableSchedule
+*********************
+
+This API enables the scheduling service for the node. For more information, check `here <https://rainmaker.espressif.com/docs/scheduling.html>`__.
+
+.. code-block:: arduino
+
+    esp_err_t enableSchedule();
+
+
+This function will return
+
+1. `ESP_OK` : On success
+2. Error in case of failure
+
+
+RMaker.setTimeZone
+******************
+
+This API set's the timezone as a user friendly location string. Check
+`here <https://rainmaker.espressif.com/docs/time-service.html>`__ for a list of valid values.
+
+**NOTE** : default value is "Asia/Shanghai".
+
+This API comes into picture only when working with scheduling.
+
+.. code-block:: arduino
+
+    esp_err_t setTimeZone(const char *tz);
+
+* ``tz`` : Valid values as specified in documentation.
+
+This function will return
+
+1. `ESP_OK` : On success
+2. Error in case of failure
+
+
+ESP RainMaker Node API
+-----------------------
+
+`Node` class expose API's for node.
+
+**NOTE** : my_node is the object of Node class.
+
+
+my_node.getNodeID
+*****************
+
+It returns the unique node_id assigned to the node. This node_id is usually the MAC address of the board.
+
+.. code-block:: arduino
+
+    char * getNodeID()
+
+* ``tz`` : Valid values as specified in documentation.
+
+This function will return
+
+1. `char *` : Pointer to a NULL terminated node_id string.
+
+
+my_node.getNodeInfo
+*******************
+
+It returns pointer to the node_info_t as configured during node initialisation.
+
+.. code-block:: arduino
+
+    node_info_t * getNodeInfo();
+
+This function will return
+
+1. `node_info_t` : Pointer to the structure node_info_t on success.
+2. `NULL` : On failure.
+
+**ESP RainMaker node info**
+
+It has following data member
+
+1. char * name
+2. char * type
+3. char * fw_version
+4. char * model
+
+
+my_node.addNodeAttr
+*******************
+
+It adds a new attribute as the metadata to the node.
+
+**NOTE** : Only string values are allowed.
+
+.. code-block:: arduino
+
+    esp_err_t addNodeAttr(const char *attr_name, const char *val);
+
+* ``attr_name`` : Name of the attribute
+* ``val`` : Value of the attribute
+
+This function will return
+
+1. `ESP_OK` : On success
+2. Error in case of failure
+
+
+my_node.addDevice
+*****************
+
+It adds a device to the node.
+
+**NOTE** :
+
+- This is the mandatory API to register device to node.
+- Single Node can have multiple devices.
+- Device name should be unique for each device.
+
+.. code-block:: arduino
+
+    esp_err_t addDevice(Device device);
+
+* ``device`` : Device object
+
+This function will return
+
+1. `ESP_OK` : On success
+2. Error in case of failure
+
+
+my_node.removeDevice
+********************
+
+It removes a device from the node.
+
+.. code-block:: arduino
+
+    esp_err_t removeDevice(Device device);
+
+* ``device`` : Device object
+
+This function will return
+
+1. `ESP_OK` : On success
+2. Error in case of failure
+
+
+
+ESP RainMaker Device API
+-----------------------------
+
+`Device` class expose API's for virtual devices on the node.
+Parameterized constructor is defined which creates the virtual device on the node. Using Device class object you can create your own device.
+
+**NOTE** : my_device is the object of Device class
+
+.. code-block:: arduino
+
+    Device my_device(const char *dev_name, const char *dev_type, void *priv_data);
+
+* ``dev_name`` : Unique device name
+* ``dev_type`` : Optional device type. It can be kept NULL.
+    * Standard Device Types
+        * ESP_RMAKER_DEVICE_SWITCH
+        * ESP_RMAKER_DEVICE_LIGHTBULB
+        * ESP_RMAKER_DEVICE_FAN
+        * ESP_RMAKER_DEVICE_TEMP_SENSOR
+* ``priv_data`` : Private data associated with the device. This will be passed to the callbacks.
+
+**NOTE** : This created device should be added to the node using ``my_node.addDevice(my_device);``
+
+- Sample example
+
+.. code-block:: arduino
+
+    Device my_device("Switch");
+    Device my_device("Switch1", NULL, NULL);
+
+- Here, dev_name is compulsory, rest are optional.
+- Node can have multiple device, each device should have unique device name.
+
+**Standard Devices**
+
+- Classes are defined for the standard devices.
+- Creating object of these class creates the standard device with default parameters to it.
+- Class for standard devices
+    * Switch
+    * LightBulb
+    * TemperatureSensor
+    * Fan
+
+.. code-block:: arduino
+
+    Switch my_switch(const char *dev_name, void *priv_data, bool power);
+
+* ``dev_name`` : Unique device name by default it is "switch" for switch device.
+* ``priv_data`` : Private data associated with the device. This will be passed to the callbacks.
+* ``power`` : It is the value that can be set for primary parameter.
+
+Sample example for standard device.
+
+.. code-block:: arduino
+
+    Switch switch1;
+    Switch switch2("switch2", NULL, true);
+
+- `"switch2"` : Name for standard device.
+- `NULL` : Private data for the device, which will be used in callback.
+- `true` : Default value for the primary param, in case of switch it is power.
+
+**NOTE**: No parameter are compulsory for standard devices. However if you are creating two objects of same standard class then in that case you will have to set the device name, if not then both device will have same name which is set by default, hence device will not get create. *Device name should be unique for each device.*
+
+
+my_device.getDeviceName
+***********************
+
+It returns the name of the Device.
+
+.. code-block:: arduino
+
+    const char * getDeviceName();
+
+* ``device`` : Device object
+
+This function will return
+
+- `char *`: Returns Device name.
+
+**NOTE**: Each device on the node should have unique device name.
+
+
+my_device.addDeviceAttr
+***********************
+
+It adds attribute to the device. Device attributes are reported only once after a boot-up as part of the node configuration. Eg. Serial Number
+
+.. code-block:: arduino
+
+    esp_err_t addDeviceAttr(const char *attr_name, const char *val);
+
+* ``attr_name`` : Name of the attribute
+* ``val`` : Value of the attribute
+
+This funtion will return
+
+1. `ESP_OK` : On success
+2. Error in case  of failure
+
+
+my_device.deleteDevice
+**********************
+
+It deletes the device created using parameterized constructor.
+
+This device should be first removed from the node using `my_node.removeDevice(my_device)`.
+
+.. code-block:: arduino
+
+    esp_err_t deleteDevice();
+
+This function will return
+
+1. `ESP_OK` : On success
+2. Error in case of failure
+
+
+my_device.addXParam
+*******************
+
+It adds standard parameter to the device.
+
+**NOTE**: X is the default name by which parameter is referred, you can specify your own name to each parameter.
+
+- Eg. `my_device.addPowerParam(true)` here power parameter is referred with name Power.
+- Eg. `my_device.addHueParam(12)` here hue parameter is referred with name Hue.
+
+You can specify your own name to each parameter
+
+- Eg. `my_device.addNameParam("NickName")` here name parameter is referred with name NickName.
+- Eg. `my_device.addPowerParam(true, "FanPower")` here power parameter is referred with name FanPower.
+
+
+**Standard Parameters**
+
+* These are the standard parameters.
+    * Name : ESP_RMAKER_DEF_NAME_PARAM
+    * Power : ESP_RMAKER_DEF_POWER_NAME
+    * Brightness : ESP_RMAKER_DEF_BRIGHTNESS_NAME
+    * Hue : ESP_RMAKER_DEF_HUE_NAME
+    * Saturation : ESP_RMAKER_DEF_SATURATION_NAME
+    * Intensity : ESP_RMAKER_DEF_INTENSITY_NAME
+    * CCT : ESP_RMAKER_DEF_CCT_NAME
+    * Direction : ESP_RMAKER_DEF_DIRECTION_NAME
+    * Speed : ESP_RMAKER_DEF_SPEED_NAME
+    * Temperature : ESP_RMAKER_DEF_TEMPERATURE_NAME
+
+
+.. code-block:: arduino
+
+    esp_err_t addNameParam(const char *param_name = ESP_RMAKER_DEF_NAME_PARAM);
+    esp_err_t addPowerParam(bool val, const char *param_name = ESP_RMAKER_DEF_POWER_NAME);
+    esp_err_t addBrightnessParam(int val, const char *param_name = ESP_RMAKER_DEF_BRIGHTNESS_NAME);
+    esp_err_t addHueParam(int val, const char *param_name = ESP_RMAKER_DEF_HUE_NAME);
+    esp_err_t addSaturationParam(int val, const char *param_name = ESP_RMAKER_DEF_SATURATION_NAME);
+    esp_err_t addIntensityParam(int val, const char *param_name = ESP_RMAKER_DEF_INTENSITY_NAME);
+    esp_err_t addCCTParam(int val, const char *param_name = ESP_RMAKER_DEF_CCT_NAME);
+    esp_err_t addDirectionParam(int val, const char *param_name = ESP_RMAKER_DEF_DIRECTION_NAME);
+    esp_err_t addSpeedParam(int val, const char *param_name = ESP_RMAKER_DEF_SPEED_NAME);
+    esp_err_t addTempratureParam(float val, const char *param_name = ESP_RMAKER_DEF_TEMPERATURE_NAME);
+
+
+This function will return
+
+1. `ESP_OK` : On success
+2. Error in case of failure
+
+**NOTE** : Care should be taken while accessing name of parameter. Above mentioned are the two ways using which default name of parameters can be accessed. Either LHS or RHS.
+
+
+my_device.assignPrimaryParam
+****************************
+
+It assigns a parameter (already added using addXParam() or addParam()) as a primary parameter, which can be used by clients (phone apps specifically) to give prominence to it.
+
+.. code-block:: arduino
+
+    esp_err_t assignPrimaryParam(param_handle_t *param);
+
+* ``param`` : Handle of the parameter. It is obtained using `my_device.getParamByName()`.
+
+This function will return
+
+1. `ESP_OK` : On success
+2. Error in case of failure
+
+
+my_device.getParamByName
+************************
+
+.. code-block:: arduino
+
+    param_handle_t * getParamByName(const char *param_name);
+
+* ``param_name`` : It is the name of the parameter which was added using addXparam() or addParam().
+
+This function will return object of the parameter.
+
+
+my_device.addParam
+******************
+
+It allows user to add custom parameter to the device created using `Param` class.
+
+.. code-block:: arduino
+
+    esp_err_t addParam(Param parameter);
+
+* ``parameter`` : Object of Param
+
+This function will return
+
+1.`ESP_OK` : On success
+2. Error in case of failure
+
+**NOTE**: Param class exposes API's to create the custom parameter.
+
+
+my_device.updateAndReportParam
+******************************
+
+It updates the parameter assosicated with particular device on ESP RainMaker cloud.
+
+.. code-block:: arduino
+
+    esp_err_t updateAndReportParam(const char *param_name, value);
+
+* ``param_name`` : Name of the parameter
+* ``value`` : Value to be updated. It can be int, bool, char * , float.
+
+This function will return
+
+1. `ESP_OK` : On success
+2. Error in case of failure
+
+
+my_device.addCb
+***************
+
+It registers read and write callback for the device which will be invoked as per requests received from the cloud (or other paths as may be added in future).
+
+.. code-block:: arduino
+
+    void addCb(deviceWriteCb write_cb, deviceReadCb read_cb);
+
+* ``write_cb`` : Function with signature
+        func_name(Device \*device, Param \*param, const param_val_t val, void \*priv_data, write_ctx_t \*ctx);
+* ``read_cb`` : Function with signature
+        func_name(Device \*device, Param \*param, void \*priv_data, read_ctx_t \*ctx);
+
+
+
+
+**Parameters**
+
+**param_val_t val**
+
+Value can be accessed as below
+
+1. `bool` : val.val.b
+2. `integer` : val.val.i
+3. `float` : val.val.f
+4. `char *` : val.val.s
+
+
+
+ESP RainMaker Param API
+-----------------------
+
+`Param` class expose API's for creating custom parameters for the devices and report and update values associated with parameter to the ESP RainMaker cloud. Parameterized constructor is defined which creates custom parameter.
+
+**NOTE** : `my_param` is the object of Param class.
+
+.. code-block:: arduino
+
+    Param my_param(const char *param_name, const char *param_type, param_val_t val, uint8_t properties);
+
+* ``param_name`` : Name of the parameter
+* ``param_type`` : Type of the parameter. It is optional can be kept NULL.
+* ``val`` : Define the default value for the parameter. It should be defined using `value(int ival)` , `value(bool bval)` , `value(float fval)` , `value(char *sval)`.
+* ``properties`` : Properties of the parameter, which will be a logical OR of flags.
+    * Flags
+        * PROP_FLAG_WRITE
+        * PROP_FLAG_READ
+        * PROP_FLAG_TIME_SERIES
+        * PROP_FLAG_PERSIST
+
+Sample example :
+
+.. code-block:: arduino
+
+    Param my_param(const char *param_name, const char *param_type, param_val_t val, uint8_t properties);
+    Param my_param("bright", NULL, value(30), PROP_FLAG_READ | PROP_FLAG_WRITE | PROP_FLAG_PERSIST);
+
+**NOTE** : Parameter created using Param class should be added to the device using `my_device.addParam(my_param);`
+
+
+my_param.addUIType
+******************
+
+Add a UI type to the parameter. This will be used by the Phone apps (or other clients) to render appropriate UI for the given parameter. Please refer the RainMaker documentation
+`here <https://rainmaker.espressif.com/docs/standard-types.html#ui-elements>`__ for supported UI Types.
+
+.. code-block:: arduino
+
+    esp_err_t addUIType(const char *ui_type);
+
+* ``ui_type`` : String describing the UI Type.
+    * Standard UI Types
+        * ESP_RMAKER_UI_TOGGLE
+        * ESP_RMAKER_UI_SLIDER
+        * ESP_RMAKER_UI_DROPDOWN
+        * ESP_RMAKER_UI_TEXT
+
+This function will return
+
+1. `ESP_OK` : On success
+2. Error in case of failure
+
+
+my_param.addBounds
+******************
+
+Add bounds for an integer/float parameter. This can be used to add bounds (min/max values) for a given integer/float parameter. Eg. brightness will have bounds as 0 and 100 if it is a percentage.
+
+.. code-block:: arduino
+
+    esp_err_t addBounds(param_val_t min, param_val_t max, param_val_t step);
+
+* ``min`` : Minimum value
+* ``max`` : Maximum value
+* ``step`` : step Minimum stepping
+
+This function will return
+
+1. `ESP_OK` : On success
+2. Error in case of failure
+
+`Sample example : my_param.addBounds(value(0), value(100), value(5));`
+
+
+my_param.updateAndReport
+************************
+
+It updates the parameter and report it to ESP RainMaker cloud. This is called in callback.
+
+.. code-block:: arduino
+
+    esp_err_t updateAndReport(param_val_t val);
+
+* ``val`` : New value of the parameter
+
+This function will return
+
+1. `ESP_OK` : On success
+2. Error in case of failure
+
+**NOTE**:
+
+- This API should always be called inside device write callback, if you aimed at updating n reporting parameter values, changed via RainMaker Client (Phone App), to the ESP RainMaker cloud.
+- If not called then paramter values will not be updated to the ESP RainMaker cloud.
+
+
+printQR
+*******
+
+This API displays QR code, which is used in provisioning.
+
+.. code-block:: arduino
+
+    printQR(const char *serv_name, const char *pop, const char *transport);
+
+* ``name`` : Service name used in provisioning API.
+* ``pop`` : Proof of posession used in provisioning API.
+* ``transport`` :
+    1. `softap` : In case of provisioning using SOFTAP.
+    2. `ble` : In case of provisioning using BLE.
+
+
+RMakerFactoryReset
+******************
+
+Reset the device to factory defaults.
+
+.. code-block:: arduino
+
+    RMakerFactoryReset(int seconds);
+
+* ``seconds`` : Time in seconds after which the chip should reboot after doing a factory reset.
+
+
+RMakerWiFiReset
+***************
+
+Reset Wi-Fi credentials.
+
+.. code-block:: arduino
+
+    RMakerWiFiReset(int seconds);
+
+* ``seconds`` : Time in seconds after which the chip should reboot after doing a Wi-Fi reset.