Initial commit.

docs/Doxyfile

@@ -0,0 +1,77 @@
+# This is Doxygen configuration file
+#
+# Doxygen provides over 260 configuration statements
+# To make this file easier to follow,
+# it contains only statements that are non-default
+#
+# NOTE:
+# It is recommended not to change defaults unless specifically required
+# Test any changes how they affect generated documentation
+# Make sure that correct warnings are generated to flag issues with documented code
+#
+# For the complete list of configuration statements see:
+# https://www.stack.nl/~dimitri/doxygen/manual/config.html
+
+
+PROJECT_NAME = "ESP RainMaker Programming Guide"
+
+## The 'INPUT' statement below is used as input by script 'gen-df-input.py'
+## to automatically generate API reference list files heder_file.inc
+## These files are placed in '_inc' directory
+## and used to include in API reference documentation
+
+INPUT = \
+    $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_core.h \
+    $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_user_mapping.h \
+    $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_schedule.h \
+    $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_scenes.h \
+    $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_standard_types.h \
+    $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_standard_params.h \
+    $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_standard_devices.h \
+    $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_standard_services.h \
+    $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_ota.h \
+    $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_mqtt.h \
+    $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_console.h \
+    $(PROJECT_PATH)/components/rmaker_common/include/esp_rmaker_common_events.h \
+    $(PROJECT_PATH)/components/rmaker_common/include/esp_rmaker_factory.h \
+    $(PROJECT_PATH)/components/rmaker_common/include/esp_rmaker_work_queue.h \
+    $(PROJECT_PATH)/components/rmaker_common/include/esp_rmaker_utils.h \
+    $(PROJECT_PATH)/components/rmaker_common/include/esp_rmaker_cmd_resp.h \
+    $(PROJECT_PATH)/components/rmaker_common/include/esp_rmaker_mqtt_glue.h
+
+## Get warnings for functions that have no documentation for their parameters or return value
+##
+WARN_NO_PARAMDOC = YES
+
+## Enable preprocessing and remove __attribute__(...) expressions from the INPUT files
+##
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+PREDEFINED             = \
+    $(ENV_DOXYGEN_DEFINES)
+
+## Extract all
+EXTRACT_ALL = YES
+
+## Do not complain about not having dot
+##
+HAVE_DOT = NO
+
+## Generate XML that is required for Breathe
+##
+GENERATE_XML    = YES
+XML_OUTPUT      = xml
+
+GENERATE_HTML   = NO
+HAVE_DOT        = NO
+GENERATE_LATEX  = NO
+GENERATE_MAN    = YES
+GENERATE_RTF    = NO
+
+## Skip distracting progress messages
+##
+QUIET = YES
+## Log warnings in a file for further review
+##
+WARN_LOGFILE = "doxygen-warning-log.txt"

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -W
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,15 @@
+# Documentation Source Folder
+
+This folder contains source files of **ESP RainMaker API documentation**.
+
+# Hosted Documentation
+
+* Check the following link for the documentation: https://docs.espressif.com/projects/esp-rainmaker/en/latest/
+
+The above URL is for the master branch latest version.
+
+# Building Documentation
+
+* ESP RainMaker uses esp-docs for building the docs.
+* Change to the docs directory and run `build-docs -l en -t esp32`
+* To understand more about ESP-Docs, please follow https://docs.espressif.com/projects/esp-docs.

docs/_static/theme_overrides.css

@@ -0,0 +1,54 @@
+/* @import 'sphinx-rtd-theme.css' */
+
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+  .wy-table-responsive table td {
+    /* !important prevents the common CSS stylesheets from overriding
+       this as on RTD they are loaded after this stylesheet */
+    white-space: normal !important;
+  }
+
+  .wy-table-responsive {
+    overflow: visible !important;
+  }
+}
+
+.wy-side-nav-search {
+  background-color: #e3e3e3 !important;
+}
+
+.wy-side-nav-search input[type=text] {
+   border-radius: 0px !important;
+   border-color: #333333 !important;
+}
+
+.icon-home {
+  color: #333333 !important;
+}
+
+.icon-home:hover {
+  background-color: #d6d6d6 !important;
+}
+
+.version {
+  color: #000000 !important;
+}
+
+a:hover {
+  color: #bd2c2a !important;
+}
+
+.logo {
+  width: 240px !important;
+}
+
+/* For space between the return type and function name */
+a.internal + code.descname::before {
+  content: ' ';
+}
+
+/* For space between the arguments of the function */
+a.internal + em::before {
+  content: ' ';
+}

docs/conf_common.py

@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+#
+# Common (non-language-specific) configuration for Sphinx
+#
+
+# type: ignore
+# pylint: disable=wildcard-import
+# pylint: disable=undefined-variable
+
+from __future__ import print_function, unicode_literals
+
+from esp_docs.conf_docs import *  # noqa: F403,F401
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('.'))
+
+extensions += ['sphinx_copybutton',
+               # Needed as a trigger for running doxygen
+               'esp_docs.esp_extensions.dummy_build_system',
+               'esp_docs.esp_extensions.run_doxygen',
+               'sphinx.ext.autodoc'
+               ]
+
+# link roles config
+github_repo = 'espressif/esp-rainmaker'
+
+# context used by sphinx_idf_theme
+html_context['github_user'] = 'espressif'
+html_context['github_repo'] = 'esp-rainmaker'
+html_static_path = ['../_static']
+
+# Extra options required by sphinx_idf_theme
+project_slug = 'esp-rainmaker'
+
+idf_targets = ['esp32', 'esp32s3', 'esp32c2', 'esp32c3']
+languages = ['en']

docs/en/c-api-reference/index.rst

@@ -0,0 +1,12 @@
+C API Reference
+================
+
+.. toctree::
+   :maxdepth: 4
+
+   rainmaker_core.rst
+   rainmaker_standard_types.rst
+   rainmaker_mqtt.rst
+   rainmaker_ota.rst
+   rainmaker_console.rst
+   rainmaker_common.rst

docs/en/c-api-reference/rainmaker_common.rst

@@ -0,0 +1,18 @@
+RainMaker Common
+################
+
+Utilities
+---------
+.. include-build-file:: inc/esp_rmaker_utils.inc
+
+Factory Storage
+---------------
+.. include-build-file:: inc/esp_rmaker_factory.inc
+
+Work Queue
+----------
+.. include-build-file:: inc/esp_rmaker_work_queue.inc
+
+Common Events
+-------------
+.. include-build-file:: inc/esp_rmaker_common_events.inc

docs/en/c-api-reference/rainmaker_console.rst

@@ -0,0 +1,3 @@
+RainMaker Console
+#################
+.. include-build-file:: inc/esp_rmaker_console.inc

docs/en/c-api-reference/rainmaker_core.rst

@@ -0,0 +1,18 @@
+RainMaker Core
+##############
+
+Core
+----
+.. include-build-file:: inc/esp_rmaker_core.inc
+
+User Mapping
+------------
+.. include-build-file:: inc/esp_rmaker_user_mapping.inc
+
+Scheduling
+----------
+.. include-build-file:: inc/esp_rmaker_schedule.inc
+
+Scenes
+------
+.. include-build-file:: inc/esp_rmaker_scenes.inc

docs/en/c-api-reference/rainmaker_mqtt.rst

@@ -0,0 +1,3 @@
+RainMaker MQTT
+##############
+.. include-build-file:: inc/esp_rmaker_mqtt.inc

docs/en/c-api-reference/rainmaker_ota.rst

@@ -0,0 +1,3 @@
+RainMaker OTA
+#############
+.. include-build-file:: inc/esp_rmaker_ota.inc

docs/en/c-api-reference/rainmaker_standard_types.rst

@@ -0,0 +1,18 @@
+RainMaker Standard Types
+########################
+
+Standard Types
+--------------
+.. include-build-file:: inc/esp_rmaker_standard_types.inc
+
+Standard Parameters
+-------------------
+.. include-build-file:: inc/esp_rmaker_standard_params.inc
+
+Standard Devices
+----------------
+.. include-build-file:: inc/esp_rmaker_standard_devices.inc
+
+Standard Services
+-----------------
+.. include-build-file:: inc/esp_rmaker_standard_services.inc

docs/en/conf.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+#
+# English Language RTD & Sphinx config file
+#
+# Uses ../conf_common.py for most non-language-specific settings.
+
+# Importing conf_common adds all the non-language-specific
+# parts to this conf module
+try:
+    from conf_common import *  # noqa: F403,F401
+except ImportError:
+    import os
+    import sys
+    sys.path.insert(0, os.path.abspath('../'))
+    from conf_common import *  # noqa: F403,F401
+
+import datetime
+
+sys.path.append(os.path.abspath('../../cli/'))
+autodoc_mock_imports = ["pathlib", "cryptography", "nvs_partition_gen", "oauth2client", "serial", "user_mapping", "rmaker_tools.rmaker_prov.esp_rainmaker_prov", "rmaker_tools.rmaker_prov.security", "rmaker_tools.rmaker_prov.prov", "rmaker_tools.rmaker_prov.prov_util", "rmaker_tools.rmaker_claim.claim"]
+
+current_year = datetime.datetime.now().year
+# -- Project information -----------------------------------------------------
+
+project = u'ESP RainMaker Programming Guide'
+copyright = u'2020, Espressif Systems (Shanghai) CO., LTD'
+author = 'Espressif'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = 'en'

docs/en/index.rst

@@ -0,0 +1,12 @@
+ESP RainMaker Programming Guide
+===============================
+ESP RainMaker is an end-to-end solution offered by Espressif to enable remote control and monitoring for products based on ESP32 series of SoCs (e.g., ESP32, ESP32-S2, ESP32-C3, ESP32-C6, ESP32-C2, etc.) without any configuration required in the Cloud. It provides a device SDK, self-adapting phone apps, transparent cloud middleware and host utilities to reduce complexity in development of connected devices.
+
+This is the C API (for firmware) and Python API (for host tools) documentation for ESP RainMaker. All other documentation can be found at `http://rainmaker.espressif.com <http://rainmaker.espressif.com>`_
+
+.. _C API Reference: c-api-reference/index.html
+
+.. toctree::
+   :hidden:
+
+   c-api-reference/index

docs/local_util.py

@@ -0,0 +1,77 @@
+# Utility functions used in conf.py
+#
+# Copyright 2017 Espressif Systems (Shanghai) PTE LTD
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http:#www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import unicode_literals
+from io import open
+import os
+import shutil
+
+try:
+    import urllib.request
+    _urlretrieve = urllib.request.urlretrieve
+except ImportError:
+    # Python 2 fallback
+    import urllib
+    _urlretrieve = urllib.urlretrieve
+
+
+def run_cmd_get_output(cmd):
+    return os.popen(cmd).read().strip()
+
+
+def files_equal(path_1, path_2):
+    if not os.path.exists(path_1) or not os.path.exists(path_2):
+        return False
+    file_1_contents = ''
+    with open(path_1, "r", encoding='utf-8') as f_1:
+        file_1_contents = f_1.read()
+    file_2_contents = ''
+    with open(path_2, "r", encoding='utf-8') as f_2:
+        file_2_contents = f_2.read()
+    return file_1_contents == file_2_contents
+
+
+def copy_file_if_modified(src_file_path, dst_file_path):
+    if not files_equal(src_file_path, dst_file_path):
+        dst_dir_name = os.path.dirname(dst_file_path)
+        if not os.path.isdir(dst_dir_name):
+            os.makedirs(dst_dir_name)
+        shutil.copy(src_file_path, dst_file_path)
+
+
+def copy_if_modified(src_path, dst_path):
+    if os.path.isfile(src_path):
+        copy_file_if_modified(src_path, dst_path)
+        return
+
+    src_path_len = len(src_path)
+    for root, dirs, files in os.walk(src_path):
+        for src_file_name in files:
+            src_file_path = os.path.join(root, src_file_name)
+            dst_file_path = os.path.join(dst_path + root[src_path_len:], src_file_name)
+            copy_file_if_modified(src_file_path, dst_file_path)
+
+
+def download_file_if_missing(from_url, to_path):
+    filename_with_path = to_path + "/" + os.path.basename(from_url)
+    exists = os.path.isfile(filename_with_path)
+    if exists:
+        print("The file '%s' already exists" % (filename_with_path))
+    else:
+        tmp_file, header = _urlretrieve(from_url)
+        with open(filename_with_path, 'wb') as fobj:
+            with open(tmp_file, 'rb') as tmp:
+                fobj.write(tmp.read())

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,4 @@
+# This is a list of python packages used to generate documentation. This file is used with pip:
+# pip install --user -r requirements.txt
+#
+esp-docs==0.2.4

docs/utils.sh

@@ -0,0 +1,18 @@
+# Bash helper functions for adding SSH keys
+
+function add_ssh_keys() {
+  local key_string="${1}"
+  mkdir -p ~/.ssh
+  chmod 700 ~/.ssh
+  echo -n "${key_string}" >~/.ssh/id_rsa_base64
+  base64 --decode --ignore-garbage ~/.ssh/id_rsa_base64 >~/.ssh/id_rsa
+  chmod 600 ~/.ssh/id_rsa
+}
+
+function add_doc_server_ssh_keys() {
+  local key_string="${1}"
+  local server_url="${2}"
+  local server_user="${3}"
+  add_ssh_keys "${key_string}"
+  echo -e "Host ${server_url}\n\tStrictHostKeyChecking no\n\tUser ${server_user}\n" >>~/.ssh/config
+}