diff --git a/.gitignore/.gitignore b/.gitignore similarity index 67% rename from .gitignore/.gitignore rename to .gitignore index 1b41a4ed..bf257711 100644 --- a/.gitignore/.gitignore +++ b/.gitignore @@ -1,9 +1,10 @@ # Doc build artifacts -docs/*/_build/ +en_build/* # docs/*/doxygen-warning-log.txt # docs/*/sphinx-warning-log.txt # docs/*/sphinx-warning-log-sanitized.txt -docs/*/xml/ -docs/*/xml_in/ -docs/*/man/ +# ./*/xml/ +# ./*/xml_in/ +# ./*/man/ # docs/doxygen_sqlite3.db +en_build/html/searchindex.js diff --git a/_static/ESP32CAM_Browser.png b/_static/ESP32CAM_Browser.png new file mode 100644 index 00000000..dae1e500 Binary files /dev/null and b/_static/ESP32CAM_Browser.png differ diff --git a/_static/ESP32CAM_M5CAM.png b/_static/ESP32CAM_M5CAM.png new file mode 100644 index 00000000..61b396a4 Binary files /dev/null and b/_static/ESP32CAM_M5CAM.png differ diff --git a/_static/ESP32CAM_Terminal.png b/_static/ESP32CAM_Terminal.png new file mode 100644 index 00000000..3c5763a9 Binary files /dev/null and b/_static/ESP32CAM_Terminal.png differ diff --git a/_static/FactoryTest_result.png b/_static/FactoryTest_result.png new file mode 100644 index 00000000..ab97ede8 Binary files /dev/null and b/_static/FactoryTest_result.png differ diff --git a/_static/M5Stack_MicroPython_UserGuidePictures/WebIDE_check_code.png b/_static/M5Stack_MicroPython_UserGuidePictures/WebIDE_check_code.png new file mode 100644 index 00000000..202c78bb Binary files /dev/null and b/_static/M5Stack_MicroPython_UserGuidePictures/WebIDE_check_code.png differ diff --git a/_static/M5Stack_MicroPython_UserGuidePictures/check_code_on_m5stack.png b/_static/M5Stack_MicroPython_UserGuidePictures/check_code_on_m5stack.png new file mode 100644 index 00000000..b04f65b0 Binary files /dev/null and b/_static/M5Stack_MicroPython_UserGuidePictures/check_code_on_m5stack.png differ diff --git a/_static/M5Stack_MicroPython_UserGuidePictures/create_a_new_project.png b/_static/M5Stack_MicroPython_UserGuidePictures/create_a_new_project.png new file mode 100644 index 00000000..eb1bc1c7 Binary files /dev/null and b/_static/M5Stack_MicroPython_UserGuidePictures/create_a_new_project.png differ diff --git a/_static/M5Stack_MicroPython_UserGuidePictures/display_hello_world.png b/_static/M5Stack_MicroPython_UserGuidePictures/display_hello_world.png new file mode 100644 index 00000000..d4ffae69 Binary files /dev/null and b/_static/M5Stack_MicroPython_UserGuidePictures/display_hello_world.png differ diff --git a/_static/M5Stack_MicroPython_UserGuidePictures/download_m5cloud_firmware_to_m5stack_board.png b/_static/M5Stack_MicroPython_UserGuidePictures/download_m5cloud_firmware_to_m5stack_board.png new file mode 100644 index 00000000..9a8d514f Binary files /dev/null and b/_static/M5Stack_MicroPython_UserGuidePictures/download_m5cloud_firmware_to_m5stack_board.png differ diff --git a/_static/M5Stack_MicroPython_UserGuidePictures/hello_world_prj.png b/_static/M5Stack_MicroPython_UserGuidePictures/hello_world_prj.png new file mode 100644 index 00000000..938887b5 Binary files /dev/null and b/_static/M5Stack_MicroPython_UserGuidePictures/hello_world_prj.png differ diff --git a/_static/M5Stack_MicroPython_UserGuidePictures/linux_check_usb_port.png b/_static/M5Stack_MicroPython_UserGuidePictures/linux_check_usb_port.png new file mode 100644 index 00000000..d7e2191b Binary files /dev/null and b/_static/M5Stack_MicroPython_UserGuidePictures/linux_check_usb_port.png differ diff --git a/_static/M5Stack_MicroPython_UserGuidePictures/linux_m5cloud_firmware_name.png b/_static/M5Stack_MicroPython_UserGuidePictures/linux_m5cloud_firmware_name.png new file mode 100644 index 00000000..774a8486 Binary files /dev/null and b/_static/M5Stack_MicroPython_UserGuidePictures/linux_m5cloud_firmware_name.png differ diff --git a/_static/M5Stack_MicroPython_UserGuidePictures/m5stack_connet_wifi.png b/_static/M5Stack_MicroPython_UserGuidePictures/m5stack_connet_wifi.png new file mode 100644 index 00000000..a86ae2d6 Binary files /dev/null and b/_static/M5Stack_MicroPython_UserGuidePictures/m5stack_connet_wifi.png differ diff --git a/_static/M5Stack_MicroPython_UserGuidePictures/register_m5stack_acount.png b/_static/M5Stack_MicroPython_UserGuidePictures/register_m5stack_acount.png new file mode 100644 index 00000000..21158d9c Binary files /dev/null and b/_static/M5Stack_MicroPython_UserGuidePictures/register_m5stack_acount.png differ diff --git a/_static/M5Stack_MicroPython_UserGuidePictures/webIDE_binding_device_interface.png b/_static/M5Stack_MicroPython_UserGuidePictures/webIDE_binding_device_interface.png new file mode 100644 index 00000000..ae2091fa Binary files /dev/null and b/_static/M5Stack_MicroPython_UserGuidePictures/webIDE_binding_device_interface.png differ diff --git a/_static/M5Stack_MicroPython_UserGuidePictures/wifi_connect_successfully.png b/_static/M5Stack_MicroPython_UserGuidePictures/wifi_connect_successfully.png new file mode 100644 index 00000000..41c96780 Binary files /dev/null and b/_static/M5Stack_MicroPython_UserGuidePictures/wifi_connect_successfully.png differ diff --git a/_static/M5Stack_MicroPython_UserGuidePictures/wifisetup.png b/_static/M5Stack_MicroPython_UserGuidePictures/wifisetup.png new file mode 100644 index 00000000..900bc566 Binary files /dev/null and b/_static/M5Stack_MicroPython_UserGuidePictures/wifisetup.png differ diff --git a/_static/M5Stack_MicroPython_UserGuidePictures/windows_connect_m5stack_AP.png b/_static/M5Stack_MicroPython_UserGuidePictures/windows_connect_m5stack_AP.png new file mode 100644 index 00000000..262809c7 Binary files /dev/null and b/_static/M5Stack_MicroPython_UserGuidePictures/windows_connect_m5stack_AP.png differ diff --git a/_static/M5Stack_MicroPython_UserGuidePictures/windows_download_firmware.png b/_static/M5Stack_MicroPython_UserGuidePictures/windows_download_firmware.png new file mode 100644 index 00000000..d70843bf Binary files /dev/null and b/_static/M5Stack_MicroPython_UserGuidePictures/windows_download_firmware.png differ diff --git a/_static/about-doc.png b/_static/about-doc.png new file mode 100644 index 00000000..f52f1658 Binary files /dev/null and b/_static/about-doc.png differ diff --git a/_static/api-reference.gif b/_static/api-reference.gif new file mode 100644 index 00000000..7fd81755 Binary files /dev/null and b/_static/api-reference.gif differ diff --git a/_static/arduino_cc_package.png b/_static/arduino_cc_package.png new file mode 100644 index 00000000..4ebf5bf8 Binary files /dev/null and b/_static/arduino_cc_package.png differ diff --git a/_static/arduino_path.png b/_static/arduino_path.png new file mode 100644 index 00000000..f88b1bae Binary files /dev/null and b/_static/arduino_path.png differ diff --git a/_static/arduino_windows_installer.png b/_static/arduino_windows_installer.png new file mode 100644 index 00000000..48fe3042 Binary files /dev/null and b/_static/arduino_windows_installer.png differ diff --git a/_static/choose_version.png b/_static/choose_version.png new file mode 100644 index 00000000..c8927df1 Binary files /dev/null and b/_static/choose_version.png differ diff --git a/_static/clone_esp32_idf.png b/_static/clone_esp32_idf.png new file mode 100644 index 00000000..c28d8776 Binary files /dev/null and b/_static/clone_esp32_idf.png differ diff --git a/_static/clone_esp32_idf_subdir.png b/_static/clone_esp32_idf_subdir.png new file mode 100644 index 00000000..c79a139e Binary files /dev/null and b/_static/clone_esp32_idf_subdir.png differ diff --git a/_static/contribute.gif b/_static/contribute.gif new file mode 100644 index 00000000..48a45089 Binary files /dev/null and b/_static/contribute.gif differ diff --git a/_static/download_idf.png b/_static/download_idf.png new file mode 100644 index 00000000..90d21ebd Binary files /dev/null and b/_static/download_idf.png differ diff --git a/_static/download_m5stack_lib.png b/_static/download_m5stack_lib.png new file mode 100644 index 00000000..e90782b6 Binary files /dev/null and b/_static/download_m5stack_lib.png differ diff --git a/_static/download_xtensa_tools.png b/_static/download_xtensa_tools.png new file mode 100644 index 00000000..c5156796 Binary files /dev/null and b/_static/download_xtensa_tools.png differ diff --git a/_static/get-started.gif b/_static/get-started.gif new file mode 100644 index 00000000..7a7a8023 Binary files /dev/null and b/_static/get-started.gif differ diff --git a/_static/linux-logo.png b/_static/linux-logo.png new file mode 100644 index 00000000..1112db65 Binary files /dev/null and b/_static/linux-logo.png differ diff --git a/_static/m5-arduino.png b/_static/m5-arduino.png new file mode 100644 index 00000000..231b3d2e Binary files /dev/null and b/_static/m5-arduino.png differ diff --git a/_static/m5stack-awesome.gif b/_static/m5stack-awesome.gif new file mode 100644 index 00000000..0b969c20 Binary files /dev/null and b/_static/m5stack-awesome.gif differ diff --git a/_static/m5stack-faq.gif b/_static/m5stack-faq.gif new file mode 100644 index 00000000..bc9dd36d Binary files /dev/null and b/_static/m5stack-faq.gif differ diff --git a/_static/macos-logo.png b/_static/macos-logo.png new file mode 100644 index 00000000..289d1f60 Binary files /dev/null and b/_static/macos-logo.png differ diff --git a/_static/mkdir_espressif.png b/_static/mkdir_espressif.png new file mode 100644 index 00000000..a770caa8 Binary files /dev/null and b/_static/mkdir_espressif.png differ diff --git a/_static/my_com.png b/_static/my_com.png new file mode 100644 index 00000000..cfbd437b Binary files /dev/null and b/_static/my_com.png differ diff --git a/_static/pics/ESP32CAM.jpg b/_static/pics/ESP32CAM.jpg new file mode 100644 index 00000000..675dc4ae Binary files /dev/null and b/_static/pics/ESP32CAM.jpg differ diff --git a/_static/pics/FAQ.jpg b/_static/pics/FAQ.jpg new file mode 100644 index 00000000..36176da5 Binary files /dev/null and b/_static/pics/FAQ.jpg differ diff --git a/_static/pics/M5Bala.jpg b/_static/pics/M5Bala.jpg new file mode 100644 index 00000000..87c31d01 Binary files /dev/null and b/_static/pics/M5Bala.jpg differ diff --git a/_static/pics/M5GO.jpg b/_static/pics/M5GO.jpg new file mode 100644 index 00000000..593f3a29 Binary files /dev/null and b/_static/pics/M5GO.jpg differ diff --git a/_static/pics/get-started.jpg b/_static/pics/get-started.jpg new file mode 100644 index 00000000..54491d69 Binary files /dev/null and b/_static/pics/get-started.jpg differ diff --git a/_static/pics/m5-api-reference.jpg b/_static/pics/m5-api-reference.jpg new file mode 100644 index 00000000..efcd29b4 Binary files /dev/null and b/_static/pics/m5-api-reference.jpg differ diff --git a/_static/pics/m5-arduino.jpg b/_static/pics/m5-arduino.jpg new file mode 100644 index 00000000..cc13dbc3 Binary files /dev/null and b/_static/pics/m5-arduino.jpg differ diff --git a/_static/pics/m5-awesome.jpg b/_static/pics/m5-awesome.jpg new file mode 100644 index 00000000..7d3673af Binary files /dev/null and b/_static/pics/m5-awesome.jpg differ diff --git a/_static/pics/m5-micropython.jpg b/_static/pics/m5-micropython.jpg new file mode 100644 index 00000000..f5f25a18 Binary files /dev/null and b/_static/pics/m5-micropython.jpg differ diff --git a/_static/pics/m5-stepmotor.jpg b/_static/pics/m5-stepmotor.jpg new file mode 100644 index 00000000..cd82beef Binary files /dev/null and b/_static/pics/m5-stepmotor.jpg differ diff --git a/_static/pics/m5stack-forum.jpg b/_static/pics/m5stack-forum.jpg new file mode 100644 index 00000000..9d7f84c1 Binary files /dev/null and b/_static/pics/m5stack-forum.jpg differ diff --git a/_static/pics/product-documents.jpg b/_static/pics/product-documents.jpg new file mode 100644 index 00000000..7dbec619 Binary files /dev/null and b/_static/pics/product-documents.jpg differ diff --git a/_static/project-configuration.png b/_static/project-configuration.png new file mode 100644 index 00000000..e724556c Binary files /dev/null and b/_static/project-configuration.png differ diff --git a/_static/resources.gif b/_static/resources.gif new file mode 100644 index 00000000..cde4bd80 Binary files /dev/null and b/_static/resources.gif differ diff --git a/_static/screenshots/ESP32CAM_Browser.png b/_static/screenshots/ESP32CAM_Browser.png new file mode 100644 index 00000000..dae1e500 Binary files /dev/null and b/_static/screenshots/ESP32CAM_Browser.png differ diff --git a/_static/screenshots/ESP32CAM_M5CAM.png b/_static/screenshots/ESP32CAM_M5CAM.png new file mode 100644 index 00000000..61b396a4 Binary files /dev/null and b/_static/screenshots/ESP32CAM_M5CAM.png differ diff --git a/_static/screenshots/ESP32CAM_Terminal.png b/_static/screenshots/ESP32CAM_Terminal.png new file mode 100644 index 00000000..3c5763a9 Binary files /dev/null and b/_static/screenshots/ESP32CAM_Terminal.png differ diff --git a/_static/screenshots/FactoryTest_result.png b/_static/screenshots/FactoryTest_result.png new file mode 100644 index 00000000..ab97ede8 Binary files /dev/null and b/_static/screenshots/FactoryTest_result.png differ diff --git a/_static/screenshots/arduino_cc_package.png b/_static/screenshots/arduino_cc_package.png new file mode 100644 index 00000000..4ebf5bf8 Binary files /dev/null and b/_static/screenshots/arduino_cc_package.png differ diff --git a/_static/screenshots/arduino_path.png b/_static/screenshots/arduino_path.png new file mode 100644 index 00000000..f88b1bae Binary files /dev/null and b/_static/screenshots/arduino_path.png differ diff --git a/_static/screenshots/arduino_windows_installer.png b/_static/screenshots/arduino_windows_installer.png new file mode 100644 index 00000000..48fe3042 Binary files /dev/null and b/_static/screenshots/arduino_windows_installer.png differ diff --git a/_static/screenshots/clone_esp32_idf.png b/_static/screenshots/clone_esp32_idf.png new file mode 100644 index 00000000..c28d8776 Binary files /dev/null and b/_static/screenshots/clone_esp32_idf.png differ diff --git a/_static/screenshots/clone_esp32_idf_subdir.png b/_static/screenshots/clone_esp32_idf_subdir.png new file mode 100644 index 00000000..c79a139e Binary files /dev/null and b/_static/screenshots/clone_esp32_idf_subdir.png differ diff --git a/_static/screenshots/download_idf.png b/_static/screenshots/download_idf.png new file mode 100644 index 00000000..90d21ebd Binary files /dev/null and b/_static/screenshots/download_idf.png differ diff --git a/_static/screenshots/download_m5stack_lib.png b/_static/screenshots/download_m5stack_lib.png new file mode 100644 index 00000000..e90782b6 Binary files /dev/null and b/_static/screenshots/download_m5stack_lib.png differ diff --git a/_static/screenshots/download_xtensa_tools.png b/_static/screenshots/download_xtensa_tools.png new file mode 100644 index 00000000..c5156796 Binary files /dev/null and b/_static/screenshots/download_xtensa_tools.png differ diff --git a/_static/screenshots/mkdir_espressif.png b/_static/screenshots/mkdir_espressif.png new file mode 100644 index 00000000..a770caa8 Binary files /dev/null and b/_static/screenshots/mkdir_espressif.png differ diff --git a/_static/screenshots/my_com.png b/_static/screenshots/my_com.png new file mode 100644 index 00000000..cfbd437b Binary files /dev/null and b/_static/screenshots/my_com.png differ diff --git a/_static/screenshots/select_arduino_install_path.png b/_static/screenshots/select_arduino_install_path.png new file mode 100644 index 00000000..e0e0db86 Binary files /dev/null and b/_static/screenshots/select_arduino_install_path.png differ diff --git a/_static/screenshots/select_arduino_lib.png b/_static/screenshots/select_arduino_lib.png new file mode 100644 index 00000000..e820d183 Binary files /dev/null and b/_static/screenshots/select_arduino_lib.png differ diff --git a/_static/screenshots/select_board_and_com.png b/_static/screenshots/select_board_and_com.png new file mode 100644 index 00000000..4476f38d Binary files /dev/null and b/_static/screenshots/select_board_and_com.png differ diff --git a/_static/screenshots/select_demo.png b/_static/screenshots/select_demo.png new file mode 100644 index 00000000..45183285 Binary files /dev/null and b/_static/screenshots/select_demo.png differ diff --git a/_static/screenshots/select_get_exe_file.png b/_static/screenshots/select_get_exe_file.png new file mode 100644 index 00000000..9d715826 Binary files /dev/null and b/_static/screenshots/select_get_exe_file.png differ diff --git a/_static/select_arduino_install_path.png b/_static/select_arduino_install_path.png new file mode 100644 index 00000000..e0e0db86 Binary files /dev/null and b/_static/select_arduino_install_path.png differ diff --git a/_static/select_arduino_lib.png b/_static/select_arduino_lib.png new file mode 100644 index 00000000..e820d183 Binary files /dev/null and b/_static/select_arduino_lib.png differ diff --git a/_static/select_board_and_com.png b/_static/select_board_and_com.png new file mode 100644 index 00000000..4476f38d Binary files /dev/null and b/_static/select_board_and_com.png differ diff --git a/_static/select_demo.png b/_static/select_demo.png new file mode 100644 index 00000000..45183285 Binary files /dev/null and b/_static/select_demo.png differ diff --git a/_static/select_get_exe_file.png b/_static/select_get_exe_file.png new file mode 100644 index 00000000..9d715826 Binary files /dev/null and b/_static/select_get_exe_file.png differ diff --git a/_static/stepmotor_pic/show_motors_files_added.png b/_static/stepmotor_pic/show_motors_files_added.png new file mode 100644 index 00000000..6ba5f20b Binary files /dev/null and b/_static/stepmotor_pic/show_motors_files_added.png differ diff --git a/_static/stepmotor_pic/stepmotor_test.png b/_static/stepmotor_pic/stepmotor_test.png new file mode 100644 index 00000000..6147ce51 Binary files /dev/null and b/_static/stepmotor_pic/stepmotor_test.png differ diff --git a/_static/stepmotor_pic/upload_module_files.png b/_static/stepmotor_pic/upload_module_files.png new file mode 100644 index 00000000..82b16b20 Binary files /dev/null and b/_static/stepmotor_pic/upload_module_files.png differ diff --git a/_static/what-you-need.png b/_static/what-you-need.png new file mode 100644 index 00000000..328c277c Binary files /dev/null and b/_static/what-you-need.png differ diff --git a/_static/windows-logo.png b/_static/windows-logo.png new file mode 100644 index 00000000..122f53a2 Binary files /dev/null and b/_static/windows-logo.png differ diff --git a/conf.py b/conf.py new file mode 100644 index 00000000..9a781049 --- /dev/null +++ b/conf.py @@ -0,0 +1,175 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = u'M5Stack' +copyright = u'2017 - 2018, M5Stack Inc' +author = u'M5Stack' + +# The short X.Y version +version = u'' +# The full version, including alpha/beta/rc tags +release = u'1.0.1' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +from recommonmark.parser import CommonMarkParser +source_parsers = { + '.md': CommonMarkParser, +} +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +source_suffix = ['.rst', '.md'] +# source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'en' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path . +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +import sphinx_rtd_theme +html_theme = 'sphinx_rtd_theme' +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'M5Stackdoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'M5Stack.tex', u'M5Stack Documentation', + u'M5Stack', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'm5stack', u'M5Stack Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'M5Stack', u'M5Stack Documentation', + author, 'M5Stack', 'One line description of project.', + 'Miscellaneous'), +] + +# -- AutoStructify Setting ---------------------------------------------- + +# At top on conf.py (with other import statements) +import recommonmark +from recommonmark.transform import AutoStructify + +# At the bottom of conf.py +def setup(app): + app.add_config_value('recommonmark_config', { + 'url_resolver': lambda url: github_doc_root + url, + # 'auto_toc_tree_section': 'Contents', + }, True) + app.add_transform(AutoStructify) diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index ea19f450..00000000 --- a/docs/README.md +++ /dev/null @@ -1,116 +0,0 @@ -M5Stack Documents logo - -[![npm version](https://img.shields.io/npm/v/style-dictionary.svg?style=flat-square)](https://badge.fury.io/js/style-dictionary) -![license](https://img.shields.io/npm/l/style-dictionary.svg?style=flat-square) -[![Build Status](https://img.shields.io/travis/amzn/style-dictionary.svg?style=flat-square)](https://travis-ci.org/amzn/style-dictionary) -[![code climate](https://img.shields.io/codeclimate/github/amzn/style-dictionary.svg?style=flat-square)](https://codeclimate.com/github/amzn/style-dictionary) - -# M5Stack Documents -> *Style once, use everywhere.* - -A M5Stack Documentation is a system that allows you to define styles once, in a way for any platform or language to consume. A single place to create and edit your styles, and a single command exports these rules to all the places you need them - iOS, Android, CSS, JS, HTML, sketch files, style documentation, etc. It is available as a CLI through npm, but can also be used like any normal node module if you want to extend its functionality. - -When you are managing user experiences, it can be quite challenging to keep styles consistent and synchronized across multiple development platforms and devices. At the same time, designers, developers, PMs and others must be able to have consistent and up-to-date style documentation to enable effective work and communication. Even then, mistakes inevitably happen and the design may not be implemented accurately. StyleDictionary solves this by automatically generating style definitions across all platforms from a single source - removing roadblocks, errors, and inefficiencies across your workflow. - -## Watch the Demo on Youtube -[![Watch the video](assets/fake_player.png)](http://youtu.be/1HREvonfqhY) - -## The basics -__A M5Stack Documents consists of:__ -1. [Style properties](#style-properties) organized in JSON files -1. Static assets that can be used across platforms - -__What a M5Stack Documents does:__ -1. Allows the style properties and assets to be consumed in any platform or language - -Let's take a look at a very basic example. - -```json -{ - "size": { - "font": { - "small" : { "value": "10px" }, - "medium": { "value": "16px" }, - "large" : { "value": "24px" }, - "base" : { "value": "{size.font.medium.value}" } - } - } -} -``` - -Here we are creating some basic font size properties. The style property `size.font.small` is "10px" for example. The style definition size.font.base.value is automatically aliased to the value found in size.font.medium.value, so both of those resolve to "16px". - -Now what the M5Stack Documents build system will do with this information is convert it to different formats so that you can use these values in any type of codebase. From this one file you can generate any number of files like: - -```scss -$size-font-small: 10px; -$size-font-medium: 16px; -$size-font-large: 24px; -$size-font-base: 16px; -``` - -```xml -10sp -16sp -24sp -16sp -``` - -```objectivec -float const SizeFontSmall = 10.00f; -float const SizeFontMedium = 16.00f; -float const SizeFontLarge = 24.00f; -float const SizeFontBase = 16.00f; -``` - -This is a very simple example, take a deeper dive into the M5Stack Documents framework in - -The M5Stack Documents framework is completely extensible and modular so you can create any type of file from a M5Stack Documents. -If there is a new language, platform, file type, you can extend the M5Stack Documents framework to create the files you need. - -__Some other things you can build with a M5Stack Documents__ -1. Images and graphics -1. Sketch files -1. Documentation site -1. _Literally anything_ - - -## Style Properties - -> Synonyms: design token, design variable, design constant, atom - -A style property is a key/value data to describe any fundamental/atomic visual properties. This information is stored in a canonical -source, the M5Stack Documents, and transformed for use in different platforms, languages, and contexts. A simple example is a color. -A color can be represented in many ways, all of these are the same color: `#ffffff`, `rgb(255,255,255)`, `hsl(0,0,1)`. - -A M5Stack Documents organizes style properties in a structured way for easy access. Style properties are organized as a deep object -with the leaf nodes being the style properties. - -```json -{ - "color": { - "font": { - "base": { "value": "#111111" }, - "secondary": { "value": "#333333" }, - "tertiary": { "value": "#666666" }, - "inverse": { - "base": { "value": "#ffffff" } - } - } - } -} -``` - -In this example there are 4 style properties: `color.font.base`, `color.font.secondary`, `color.font.tertiary`, and `color.font.inverse.base`. -A style property is any object in the JSON that has a `value` attribute on it. In this way you can nest properties at different levels. -This allows you to easily access the property as well as do things like get all the inverse font colors. - - -## Contributing - -Please help make this framework better. For more information take a look at [CONTRIBUTING.md](https://github.com/amzn/style-dictionary/blob/master/CONTRIBUTING.md) - - -## License - -[Apache 2.0](https://github.com/amzn/style-dictionary/blob/master/LICENSE) diff --git a/docs/_coverpage.md b/docs/_coverpage.md deleted file mode 100644 index de5495c6..00000000 --- a/docs/_coverpage.md +++ /dev/null @@ -1,12 +0,0 @@ -![logo](assets/logo.png) - -# Style Dictionary - -> Style once, use everywhere. - -**Style Dictionary** is a build system that allows you to define styles once, in a way for any platform or language to consume. A single place to create and edit your styles, and a single command exports these rules to all the places you need them - iOS, Android, CSS, JS, HTML, sketch files, style documentation, or anything you can think of. It is available as a CLI through npm, but can also be used like any normal node module if you want to extend its functionality. - -[GitHub](https://github.com/amzn/style-dictionary) -[Get Started](README.md) - -![color](#D9F8F5) diff --git a/docs/_sidebar.md b/docs/_sidebar.md deleted file mode 100644 index bd3b90bb..00000000 --- a/docs/_sidebar.md +++ /dev/null @@ -1,21 +0,0 @@ -- Getting started - - [Overview](README.md) - - [Quick Start](quick_start.md) - - [Examples](examples.md) - - [Package structure](package_structure.md) - - [Extending](extending.md) - -- Reference - - [API](api.md) - - [Transforms](transforms.md) - - [Transform groups](transform_groups.md) - - [Formats](formats.md) - - [Templates](templates.md) - - [Actions](actions.md) - - [Build process](build_process.md) - -- **Links** -- [![Code](https://icongr.am/feather/code.svg?size=16&color=808080)Demo Sandbox](https://codesandbox.io/s/xv36w4695o) -- [![Github](https://icongram.jgog.in/simple/github.svg?color=808080&size=16)Github](https://github.com/jhildenbiddle/docsify-themeable) -- [![NPM](https://icongram.jgog.in/simple/npm.svg?colored&size=16)NPM](https://www.npmjs.com/package/docsify-themeable) -- [![Twitter](https://icongram.jgog.in/simple/twitter.svg?colored&size=16)@jhildenbiddle](http://twitter.com/jhildenbiddle) \ No newline at end of file diff --git a/docs/actions.md b/docs/actions.md deleted file mode 100644 index 1fe90a01..00000000 --- a/docs/actions.md +++ /dev/null @@ -1,44 +0,0 @@ -# Actions - -Actions provide a way to run custom build code such as generating binary assets like images. - -Here are all the actions that come with the Style Dictionary build system. We try to include what most people might need. You can define custom actions with the [`registerAction`](api.md#registeraction). If you think we are missing some things, take a look at our [contributing docs](https://github.com/amzn/style-dictionary/blob/master/CONTRIBUTING.md) and send us a pull request! If you have a specific need for your project, you can always write your own [custom actions](#adding-custom-actions). - -You use actions in your config file under platforms > [platform] > actions - -```json -{ - "source": ["properties/**/*.json"], - "platforms": { - "android": { - "transformGroup": "android", - "files": [], - "actions": ["copy_assets"] - } - } -} -``` - - ----- - -## Pre-defined Actions - -[lib/common/actions.js](https://github.com/amzn/style-dictionary/blob/master/lib/common/actions.js) - -### android/copyImages - - -Action to copy images into appropriate android directories. - - -* * * - -### copy_assets - - -Action that copies everything in the assets directory to a new assets directory in the build path of the platform. - - -* * * - diff --git a/docs/api.md b/docs/api.md deleted file mode 100644 index 2a3e4652..00000000 --- a/docs/api.md +++ /dev/null @@ -1,296 +0,0 @@ -# API - -### buildAllPlatforms -> StyleDictionary.buildAllPlatforms() ⇒ [style-dictionary](#module_style-dictionary) - - - - -The only top-level method that needs to be called -to build the Style Dictionary. - -**Example** -```js -const StyleDictionary = require('style-dictionary').extend('config.json'); -StyleDictionary.buildAllPlatforms(); -``` - -* * * - -### buildPlatform -> StyleDictionary.buildPlatform(platform) ⇒ [style-dictionary](#module_style-dictionary) - - - - -Takes a platform and performs all transforms to -the properties object (non-mutative) then -builds all the files and performs any actions. This is useful if you only want to -build the artifacts of one platform to speed up the build process. - -This method is also used internally in [buildAllPlatforms](#buildAllPlatforms) to -build each platform defined in the config. - - -| Param | Type | Description | -| --- | --- | --- | -| platform | String | Name of the platform you want to build. | - -**Example** -```js -StyleDictionary.buildPlatform('web'); -``` -```bash -$ style-dictionary build --platform web -``` - -* * * - -### cleanAllPlatforms -> StyleDictionary.cleanAllPlatforms() ⇒ [style-dictionary](#module_style-dictionary) - - - - -Does the reverse of [buildAllPlatforms](#buildAllPlatforms) by -performing a clean on each platform. This removes all the files -defined in the platform and calls the undo method on any actions. - - -* * * - -### cleanPlatform -> StyleDictionary.cleanPlatform(platform) ⇒ [style-dictionary](#module_style-dictionary) - - - - -Takes a platform and performs all transforms to -the properties object (non-mutative) then -cleans all the files and perfoms the undo method of any [actions](actions.md). - - -| Param | Type | -| --- | --- | -| platform | String | - - -* * * - -### exportPlatform -> StyleDictionary.exportPlatform(platform) ⇒ Object - - - - -Exports a properties object with applied -platform transforms. - -This is useful if you want to use a style -dictionary in JS build tools like webpack. - - -| Param | Type | Description | -| --- | --- | --- | -| platform | String | The platform to be exported. Must be defined on the style dictionary. | - - -* * * - -### extend -> StyleDictionary.extend(config) ⇒ [style-dictionary](#module_style-dictionary) - - - - -Create a Style Dictionary - - -| Param | Type | Description | -| --- | --- | --- | -| config | [Config](#Config) | Configuration options to build your style dictionary. If you pass a string, it will be used as a path to a JSON config file. You can also pass an object with the configuration. | - -**Example** -```js -const StyleDictionary = require('style-dictionary').extend('config.json'); - -const StyleDictionary = require('style-dictionary').extend({ - source: ['properties/*.json'], - platforms: { - scss: { - transformGroup: 'scss', - buildPath: 'build/', - files: [{ - destination: 'variables.scss', - format: 'scss/variables' - }] - } - // ... - } -}); -``` - -* * * - -### registerAction -> StyleDictionary.registerAction(action) ⇒ [style-dictionary](#module_style-dictionary) - - - - -Adds a custom action to the style property builder. Custom -actions can do whatever you need, such as: copying files, -base64'ing files, running other build scripts, etc. -After you register a custom action, you then use that -action in a platform your config.json - -Actions run after the files in a platform are generated so you -can perform operations on files generated by the style dictionary. -Actions are run sequentially, if you write synchronous code then -it will block other actions, or if you use asynchronous code like Promises -it will not block. - - -| Param | Type | Description | -| --- | --- | --- | -| action | Object | | -| action.name | String | The name of the action | -| action.do | function | The action in the form of a function. | -| [action.undo] | function | A function that undoes the action. | - -**Example** -```js -StyleDictionary.registerAction({ - name: 'copy_assets', - do: function(dictionary, config) { - console.log('Copying assets directory'); - fs.copySync('assets', config.buildPath + 'assets'); - }, - undo: function(dictionary, config) { - console.log('Cleaning assets directory'); - fs.removeSync(config.buildPath + 'assets'); - } -}); -``` - -* * * - -### registerFormat -> StyleDictionary.registerFormat(format) ⇒ [style-dictionary](#module_style-dictionary) - - - - -Add a custom format to the style dictionary - - -| Param | Type | Description | -| --- | --- | --- | -| format | Object | | -| format.name | String | Name of the format to be referenced in your config.json | -| format.formatter | function | Function to perform the format. Takes 2 arguments, `dictionary` and `config` Must return a string. | - -**Example** -```js -StyleDictionary.registerFormat({ - name: 'json', - formatter: function(dictionary, config) { - return JSON.stringify(dictionary.properties, null, 2); - } -}) -``` - -* * * - -### registerTemplate -> StyleDictionary.registerTemplate(template) ⇒ [style-dictionary](#module_style-dictionary) - - - - -Add a custom template to the Style Dictionary - - -| Param | Type | Description | -| --- | --- | --- | -| template | Object | | -| template.name | String | The name of your template. You will refer to this in your config.json file. | -| template.template | String | Path to your lodash template | - -**Example** -```js -StyleDictionary.registerTemplate({ - name: 'Swift/colors', - template: __dirname + '/templates/swift/colors.template' -}); -``` - -* * * - -### registerTransform -> StyleDictionary.registerTransform(transform) ⇒ [style-dictionary](#module_style-dictionary) - - - - -Add a custom transform to the Style Dictionary -Transforms can manipulate a property's name, value, or attributes - - -| Param | Type | Description | -| --- | --- | --- | -| transform | Object | Transform object | -| transform.type | String | Type of transform, can be: name, attribute, or value | -| transform.name | String | Name of the transformer so a transformGroup can call a list of transforms. | -| [transform.matcher] | function | Matcher function, return boolean if transform should be applied. If you omit the matcher function, it will match all properties. | -| transform.transformer | function | Performs a transform on a property object, should return a string or object depending on the type. Will only update certain properties so you can't mess up property objects on accident. | - -**Example** -```js -StyleDictionary.registerTransform({ - name: 'time/seconds', - type: 'value', - matcher: function(prop) { - return prop.attributes.category === 'time'; - }, - transformer: function(prop) { - // Note the use of prop.original.value, - // before any transforms are performed, the build system - // clones the original property to the 'original' attribute. - return (parseInt(prop.original.value) / 1000).toString() + 's'; - } -}); -``` - -* * * - -### registerTransformGroup -> StyleDictionary.registerTransformGroup(transformGroup) ⇒ [style-dictionary](#module_style-dictionary) - - - - -Add a custom transformGroup to the Style Dictionary, which is a -group of transforms. - - -| Param | Type | Description | -| --- | --- | --- | -| transformGroup | Object | | -| transformGroup.name | String | Name of the transform group that will be referenced in config.json | -| transformGroup.transforms | Array.<String> | Array of strings that reference the name of transforms to be applied in order. Transforms must be defined and match the name or there will be an error at build time. | - -**Example** -```js -StyleDictionary.registerTransformGroup({ - name: 'Swift', - transforms: [ - 'attribute/cti', - 'size/pt', - 'name/cti' - ] -}); -``` - -* * * - diff --git a/docs/assets/build-diagram.png b/docs/assets/build-diagram.png deleted file mode 100644 index 7400fc3f..00000000 Binary files a/docs/assets/build-diagram.png and /dev/null differ diff --git a/docs/assets/css/main.css b/docs/assets/css/main.css deleted file mode 100644 index c4122e59..00000000 --- a/docs/assets/css/main.css +++ /dev/null @@ -1,42 +0,0 @@ -.markdown-section iframe[src*="buttons.github.io"] { - margin: 0; -} - -figure.thumbnails img { - margin: 0.75em 0; - border-radius: 3px; - box-shadow: 0 2px 6px rgba(0,0,0,0.1), 0 4px 12px rgba(0,0,0,0.15); -} - -@media (min-width: 30em) { - figure.thumbnails:after { - content: ""; - display: table; - clear: both; - } - - figure.thumbnails img { - float: left; - width: calc(50% - 0.75em); - } - - figure.thumbnails img:nth-child(even) { - margin-left: 1.5em; - } - - @supports (display: flex) { - figure.thumbnails { - display: flex; - align-items: center; - } - - figure.thumbnails img { - flex-grow: 1; - width: 0; - } - - figure.thumbnails img + img { - margin: 0 0 0 1.5em; - } - } -} diff --git a/docs/assets/cti.png b/docs/assets/cti.png deleted file mode 100644 index 089f69c7..00000000 Binary files a/docs/assets/cti.png and /dev/null differ diff --git a/docs/assets/fake_player.png b/docs/assets/fake_player.png deleted file mode 100644 index 94343e65..00000000 Binary files a/docs/assets/fake_player.png and /dev/null differ diff --git a/docs/assets/favicon.png b/docs/assets/favicon.png deleted file mode 100644 index ca8c5ee4..00000000 Binary files a/docs/assets/favicon.png and /dev/null differ diff --git a/docs/assets/js/.eslintrc.js b/docs/assets/js/.eslintrc.js deleted file mode 100644 index 36ac1fa7..00000000 --- a/docs/assets/js/.eslintrc.js +++ /dev/null @@ -1,15 +0,0 @@ -module.exports = { - "parserOptions": { - "ecmaVersion": 5, - "sourceType": "script" - }, - "env": { - "commonjs": false, - "es6" : false, - "node" : false - }, - "rules": { - "no-var" : "off", - "prefer-const": "off" - } -} \ No newline at end of file diff --git a/docs/assets/js/main.js b/docs/assets/js/main.js deleted file mode 100644 index 1029804c..00000000 --- a/docs/assets/js/main.js +++ /dev/null @@ -1,121 +0,0 @@ -(function() { - // Functions - // ========================================================================= - /** - * Adds event listeners to change active stylesheet and restore previously - * activated stylesheet on reload. - * - * @example - * - * This link: - * Foo - * Will active this existing link: - * - * - * @example - * - * This link: - * Bar - * Will activate this existing link: - * - * Or generate this active link: - * - */ - function initStyleSwitcher() { - var isInitialzed = false; - var sessionStorageKey = 'activeStylesheetHref'; - - function handleSwitch(activeHref, activeTitle) { - var activeElm = document.querySelector('link[href*="' + activeHref +'"],link[title="' + activeTitle +'"]'); - - if (!activeElm && activeHref) { - activeElm = document.createElement('link'); - activeElm.setAttribute('href', activeHref); - activeElm.setAttribute('rel', 'stylesheet'); - activeElm.setAttribute('title', activeTitle); - - document.head.appendChild(activeElm); - - activeElm.addEventListener('load', function linkOnLoad() { - activeElm.removeEventListener('load', linkOnLoad); - setActiveLink(activeElm); - }); - } - else if (activeElm) { - setActiveLink(activeElm); - } - } - - function setActiveLink(activeElm) { - var activeHref = activeElm.getAttribute('href'); - var activeTitle = activeElm.getAttribute('title'); - var inactiveElms = document.querySelectorAll('link[title]:not([href*="' + activeHref +'"]):not([title="' + activeTitle +'"])'); - - // Remove "alternate" keyword - activeElm.setAttribute('rel', (activeElm.rel || '').replace(/\s*alternate/g, '').trim()); - - // Force enable stylesheet (required for some browsers) - activeElm.disabled = true; - activeElm.disabled = false; - - // Store active style sheet - sessionStorage.setItem(sessionStorageKey, activeHref); - - // Disable other elms - for (var i = 0; i < inactiveElms.length; i++) { - var elm = inactiveElms[i]; - - elm.disabled = true; - - // Fix for browsersync and alternate stylesheet updates. Will - // cause FOUC when switching stylesheets during development, but - // required to properly apply style updates when alternate - // stylesheets are enabled. - if (window.browsersyncObserver) { - var linkRel = elm.getAttribute('rel') || ''; - var linkRelAlt = linkRel.indexOf('alternate') > -1 ? linkRel : (linkRel + ' alternate').trim(); - - elm.setAttribute('rel', linkRelAlt); - } - } - - // CSS custom property ponyfil - if ((window.$docsify || {}).themeable) { - window.$docsify.themeable.util.cssVars(); - } - } - - // Event listeners - if (!isInitialzed) { - isInitialzed = true; - - // Restore active stylesheet - document.addEventListener('DOMContentLoaded', function() { - var activeHref = sessionStorage.getItem(sessionStorageKey); - - if (activeHref) { - handleSwitch(activeHref); - } - }); - - // Update active stylesheet - document.addEventListener('click', function(evt) { - var dataHref = evt.target.getAttribute('data-link-href'); - var dataTitle = evt.target.getAttribute('data-link-title') - - if (dataHref || dataTitle) { - dataTitle = dataTitle - || evt.target.textContent - || '_' + Math.random().toString(36).substr(2, 9); // UID - - handleSwitch(dataHref, dataTitle); - evt.preventDefault(); - } - }); - } - } - - // Main - // ========================================================================= - initStyleSwitcher(); -})(); diff --git a/docs/assets/logo.png b/docs/assets/logo.png deleted file mode 100644 index 9715805e..00000000 Binary files a/docs/assets/logo.png and /dev/null differ diff --git a/docs/assets/styles.css b/docs/assets/styles.css deleted file mode 100644 index aef12471..00000000 --- a/docs/assets/styles.css +++ /dev/null @@ -1,393 +0,0 @@ -:root { - --theme-color: #1FC5BF; - --theme-color-light: #99EBE2; - --theme-color-dark: #00B3AC; - --theme-color-secondary: #6A5096; - --theme-color-secondary-dark: #3F1C77; - --theme-color-secondary-light: #C4B2E1; - - --text-color-base: #2E2E46; - --text-color-secondary: #646473; - --text-color-tertiary: #81818E; -} - - -::selection { - background: var(--theme-color-light); -} - -body { - font-size: 100%; - line-height: 1.5; - font-family: 'Source Sans Pro','Open Sans','Helvetica Neue',Arial,sans-serif; - color: var(--text-color-base); -} - -* { - text-decoration: none !important; -} - -a { - transition: all 0.3s linear; -} - -div.search { - border-bottom: 2px solid #787881; - border: none; - background-color: var(--theme-color-secondary-light); - padding: 0; -} - -.sidebar .search input { - background: none; - background-color: rgba(255,255,255,0.5); - padding: 1rem; - transition: background-color 0.3s ease; -} - -.sidebar .search input:focus { - background-color: rgba(255,255,255,1); -} - -aside.sidebar { - border: none; - background-color: var(--theme-color-secondary); - color: #fff; - width: 20%; -} - -body.close .sidebar { - transform: translateX(-100%); -} - -.sidebar ul li a { - color: rgba(255,255,255,0.8); - color: var(--theme-color-light); - font-size: 1rem; -} - -.sidebar ul li.active>a { - border-width: 0.1rem; -} - -.sidebar ul li a:hover { - text-decoration: none; - color: rgba(255,255,255,1); -} - -.sidebar .sidebar-nav ul li.active>a { - color: #fff; - border-right: 0.2rem solid var(--theme-color-secondary-light,#29D0CA); -} - -.search .results-panel.show { - background-color: #05827E; - background-color: #fff; - color: #000; -} - -.sidebar .search .matching-post { - padding: 0; - border-bottom: 0.2rem solid #E4E4E6; -} - -.sidebar .search .matching-post:first-child { - border-top: 0.2rem solid #E4E4E6; -} - -.search .search-keyword { - /* color: #fff; */ -} - -.search a { - padding: 1rem; - display: block; - transition: background-color 0.3s ease; -} - -.search a:hover { - color: var(--theme-color-dark); -} - -.search p.empty { - margin: 0; - padding: 1rem; - background-color: #F1F1F2; -} - -.sidebar > h1 { - font-size: 2rem; -} - -.sidebar-logo { - display: block; - width: 4rem; - vertical-align: bottom; - line-height: 1.6; - height: 4rem; - margin: 0 auto; -} - -body .sidebar-toggle { - background: none; - bottom: 1rem; - left: 1rem; - cursor: pointer; - width: 1.5rem; - height: 1.5rem; - padding: 0; -} - -body .sidebar-toggle span { - transition: all 0.3s linear; - background-color: var(--theme-color-light); - height: 0.25rem; - width: 1.5rem; - position: absolute; - left: 0; - margin: 0; - transform-origin: 0; -} - -body.close .sidebar-toggle { - width: 1.5rem; - height: 1.5rem; -} - -body.close .sidebar-toggle span { - transform-origin: center; -} - -body .sidebar-toggle span:nth-child(1) { top:0; } -body .sidebar-toggle span:nth-child(2) { top:0.65rem; } -body .sidebar-toggle span:nth-child(3) { top:1.25rem; } - -.sidebar-toggle .sidebar-toggle-button:hover { opacity: 1; } - -.sidebar-toggle:hover span:nth-child(1) { transform: rotate(45deg); width: 1.75rem; } -.sidebar-toggle:hover span:nth-child(2) { opacity: 0; } -.sidebar-toggle:hover span:nth-child(3) { transform: rotate(-45deg); width: 1.75rem; } - -.close .sidebar-toggle:hover span:nth-child(1) { transform:rotate(0); width:1.5rem; top:0.65rem; } -.close .sidebar-toggle:hover span:nth-child(2) { opacity: 1; transform:rotate(90deg); } -.close .sidebar-toggle:hover span:nth-child(3) { transform:rotate(0); width:1.5rem; top:0.65rem; } - -th { - text-align: left; -} - -.markdown-section blockquote { - margin: 1em 0; -} - -.markdown-section em, -.markdown-section blockquote { - color: var(--text-color-tertiary); -} - -.cover-main img { - max-width: 10rem; - max-height: 10rem; -} - -section.cover p { - line-height: inherit; -} - -section.cover .cover-main a { - font-weight: 600; -} - -section.cover .cover-main a::before { - display: none; -} - -section.cover .cover-main blockquote { - font-style: italic; - color: #868C91; -} - -section.cover .cover-main>p:last-child a:first-child { - border-width: 0.2rem; - color: var(--theme-color-secondary); - border-color: var(--theme-color-secondary); -} - -section.cover .cover-main>p:last-child a:last-child { - background-color: var(--theme-color-secondary); - border-color: var(--theme-color-secondary); -} - -section.cover .cover-main>p:last-child a:hover { - color: var(--theme-color-secondary-dark); - border-color: var(--theme-color-secondary-dark); - opacity: 1; -} - -section.cover .cover-main>p:last-child a:last-child:hover { - background-color: var(--theme-color-secondary-dark); - border-color: var(--theme-color-secondary-dark); - color: #fff; - opacity: 1; -} - -.anchor { - position: relative; -} - -.anchor::before { - content: '\1F449'; - position: absolute; - top: 0; - left: -1.25em; - opacity: 0; - font-size: 0.875em; -} - -.anchor:hover::before { - opacity: 1; -} - -section.cover .cover-main { - margin: 20vh 20vw; -} - -.app-name-link { - white-space: nowrap; -} - -.app-sub-sidebar li:before { - display: none; -} - -.markdown-section pre, -.markdown-section pre > code { - background-color: #2E2E46; - color: rgba(255,255,255,0.75); - font-size: 1em; - line-height: 1.5; -} - -.markdown-section code { - display: inline-block; - font-family: 'Source Code Pro', monospace; -} - -.markdown-section pre { - padding: 2rem; -} - -.markdown-section pre > code { - padding: 0; -} - -.markdown-section hr { - border-bottom: 5px solid transparent; -} - -.token.punctuation { - color: #585967; -} - -.token.comment, -.token.block-comment, -.token.prolog, -.token.doctype, -.token.cdata{color:#999999;} -.token.property, -.token.number, -.token.function-name, -.token.constant, -.token.symbol, -.token.deleted{color:#5a9bcf;}.token.boolean{color:#ff8b50;}.token.tag{color:#fc929e;}.token.string{color:#8dc891;}.token.punctuation{color:#5FB3B3;} -.token.selector, -.token.char, -.token.builtin, -.token.inserted{color:#D8DEE9;}.token.function{color:#79b6f2;} -.token.operator, -.token.entity, -.token.url, -.token.variable{color:#d7deea;}.token.attr-value{color:#8dc891;}.token.keyword{color:#c5a5c5;} - -.lang-scss .token.variable { - color: #8dc891; -} - -.markdown-section { - max-width: 75rem; - padding: 1rem 3rem; -} - -.markdown-section ol, .markdown-section p, .markdown-section ul { - line-height: inherit; -} - -.markdown-section code { - color: inherit; - border-radius: 0; - font-size: 0.9em; - padding: 6px 10px; - /* color: #111; */ -} - -.markdown-section table { - display: table; -} - -.markdown-section table tr { - border-width: 0.2rem 0; - border-style: solid; - border-color: #F1F1F2; -} - -.markdown-section table tr:nth-child(2n) { - background-color: transparent; -} - -.markdown-section table td, -.markdown-section table th { - border: none; - padding: 1.5rem 0.5rem; - text-align: left; -} - -.markdown-section table td p { - margin: 0; -} - -.markdown-section a { - text-decoration: none; - border-bottom: 0.1rem solid var(--theme-color-light); - transition: all 0.3s ease; -} - -.markdown-section a:hover { - border-color: var(--theme-color); - color: var(--theme-color-dark); -} - - -/* Badges */ -.markdown-section > p:first-child > a { - border: none; -} - -.docsify-copy-code-button { - background: var(--theme-color); -} - -.sidebar::-webkit-scrollbar { - width:0; -} - -@media (min-width: 1200px) { - body { - font-size: 112.5%; - } -} - -@media (min-width: 1400px) { - body { - font-size: 125%; - } -} diff --git a/docs/build_process.md b/docs/build_process.md deleted file mode 100644 index 29dab6a2..00000000 --- a/docs/build_process.md +++ /dev/null @@ -1,42 +0,0 @@ -# Build Process - -Here is what the build system is doing under the hood. - -![build structure](assets/build-diagram.png) - -## CLI - -1. The build system looks for a config file. By default it looks for config.json in the current directory, or you can specify the config path with the `-c --config` flag. -1. If there is an `includes` attribute in the config, it will take those JSON files and deep merge them into the `properties` object. -1. It then takes all the JSON files in the `source` attribute in the config and performs a deep merge onto the `properties` object. -1. Then it iterates over the platforms in the config and: - 1. Perform all transforms, in order, defined in the transforms attribute or transformGroup. - 1. Build all files defined in the files array - 1. Perform any actions defined in the actions attribute - - -## Node - -If you use this as a node module, the steps are slightly different, but the overall. - -1. When you call the [`extend`](api.md#extend) method, you can either pass it a path to a JSON config file, or give it a plain object that has the configuration. This will perform steps 1-3 above. -1. Then you can now call `buildAllPlatforms` or other methods like `buildPlatform('scss')` or `exportPlatform('javascript')`. This is equivalent to step 4 above. - -```javascript -const StyleDictionary = require('style-dictionary'); - -const styleDictionary = StyleDictionary.extend( 'config.json' ); -// is equivalent to this: -// const styleDictionary = StyleDictionary.extend( -// JSON.parse( fs.readFileSync( 'config.json' ) ) -// ) - -// You can also extend with an object -// const styleDictionary = StyleDictionary.extend({ /* config options */ }); - -// This will perform step 3 above, for each platform: -// 1. Apply transforms -// 2. Build files -// 3. Perform actions -styleDictionary.buildAllPlatforms(); -``` diff --git a/docs/examples.md b/docs/examples.md deleted file mode 100644 index 3fc4b972..00000000 --- a/docs/examples.md +++ /dev/null @@ -1,39 +0,0 @@ -# Examples - -To get you started, there are some example packages included that you can use. You can take a look at the code on Github or you -can use the CLI included to generate a new package using these examples. Here is how you can do that: -```bash -$ mkdir MyStyleD -$ cd MyStyleD -$ style-dictionary init [example] -``` -Where `[example]` is one of: `basic`, `complete`, `npm`, `s3` - -## Basic -[View on Github](https://github.com/amzn/style-dictionary/tree/master/example/basic) - -This example code is bare-bones to show you what this framework can do. Use this if you want to play around with what the Style Dictionary -can do. - - -## Complete -[View on Github](https://github.com/amzn/style-dictionary/tree/master/example/complete) - -This is a more complete package and should have everything you need to get started. This package can be consumed as a Cocoapod on iOS, -as a node module for web, and as a local library for Android. - -## npm -[View on Github](https://github.com/amzn/style-dictionary/tree/master/example/npm) - -This example shows how to set up a style dictionary as an npm module, either to publish to a local npm service or to publish externally. - -When you publish this npm module, the prepublish hook will run, calling the style dictionary build system to create the necessary files. You can also just run `npm run build` to generate the files to see what it is creating. - -## s3 -[View on Github](https://github.com/amzn/style-dictionary/tree/master/example/s3) - -One way to use the style dictionary framework is to build files for each platform and upload those build artifacts to an s3 bucket. The platforms can pull these files down during their build process. - ----- - -> More coming soon... diff --git a/docs/extending.md b/docs/extending.md deleted file mode 100644 index a925726b..00000000 --- a/docs/extending.md +++ /dev/null @@ -1,45 +0,0 @@ -# Extending - -The style dictionary build system is made to be extended. We don't know exactly how everyone will want to use style dictionaries in their project, which is why it is easy to create custom transforms, templates, and formats. - -* [registerTransform](api.md#registertransform) -* [registerTransformGroup](api.md#registertransformgroup) -* [registerFormat](api.md#registerformat) -* [registerTemplate](api.md#registertemplate) -* [registerAction](api.md#registeraction) - -```javascript -const StyleDictionary = require('style-dictionary').extend('config.json'); - -StyleDictionary.registerTransform({ - name: 'time/seconds', - type: 'value', - matcher: function(prop) { - return prop.attributes.category === 'time'; - }, - transformer: function(prop) { - return (parseInt(prop.original.value) / 1000).toString() + 's'; - } -}); - -StyleDictionary.buildAllPlatforms(); -``` - -You can also export your extended style dictionary as a node module if you need other projects to depend on it. - -```javascript -// package a -const StyleDictionary = require('style-dictionary').extend('config.json'); -StyleDictionary.registerTransform({ - name: 'name/uppercase', - type: 'name', - transformer: function(prop) { - return prop.path.join('_').toUppercase(); - } -}); - -module.exports = StyleDictionary; - -// package b -const StyleDictionary = require('package-a'); -``` diff --git a/docs/formats.md b/docs/formats.md deleted file mode 100644 index 2c7019fd..00000000 --- a/docs/formats.md +++ /dev/null @@ -1,271 +0,0 @@ -# Formats - -Formats are one of the ways to create files that act as interfaces for your style dictionary. For example, you want to be able to -use your style dictionary in CSS. You can use the `css/variables` template which will create a CSS file with variables from -your style dictionary. You can define custom formats with the [`registerFormat`](api.md#registerformat). - -Templates and Formats serve the same purpose: use your style dictionary as data to build a file. You use formats in your config -file under platforms > [platform] > files > [file] - -```json -{ - "source": ["properties/**/*.json"], - "platforms": { - "css": { - "transformGroup": "css", - "files": [ - { - "template": "css/variables", - "destination": "variables.css" - } - ] - } - } -} -``` - - ->*__How are Templates different than Formats?__* - ->Mainly syntactic sugar; anything you can do in a Template you can do in a Format. Use whichever is easier for you to write. We find -that Templates are good if you have a lot of boilerplate code around where the style dictionary will go (like writing ObjectiveC files). -Formats are better if there is little to no boilerplate code like a flat SCSS variables file. - ----- - -## Pre-defined Formats - -[lib/common/formats.js](https://github.com/amzn/style-dictionary/blob/master/lib/common/formats.js) - -### css/variables - - -Creates a CSS file with variable definitions based on the style dictionary - -**Example** -```css -:root { - --color-background-base: #f0f0f0; - --color-background-alt: #eeeeee; -} -``` - -* * * - -### scss/variables - - -Creates a SCSS file with variable definitions based on the style dictionary - -**Example** -```scss -$color-background-base: #f0f0f0; -$color-background-alt: #eeeeee; -``` - -* * * - -### scss/icons - - -Creates a SCSS file with variable definitions and helper classes for icons - -**Example** -```scss -$content-icon-email: '\E001'; -.icon.email:before { content:$content-icon-email; } -``` - -* * * - -### less/variables - - -Creates a LESS file with variable definitions based on the style dictionary - -**Example** -```less -@color-background-base: #f0f0f0; -@color-background-alt: #eeeeee; -``` - -* * * - -### less/icons - - -Creates a LESS file with variable definitions and helper classes for icons - -**Example** -```less -@content-icon-email: '\E001'; -.icon.email:before { content:@content-icon-email; } -``` - -* * * - -### javascript/module - - -Creates a CommonJS module with the whole style dictionary - -**Example** -```js -module.exports = { - color: { - base: { - red: { - value: '#ff000' - } - } - } -} -``` - -* * * - -### javascript/object - - -Creates a JS file a global var that is a plain javascript object of the style dictionary. -Name the variable by adding a 'name' attribute on the file object in your config. - -**Example** -```js -var StyleDictionary = { - color: { - base: { - red: { - value: '#ff000' - } - } - } -} -``` - -* * * - -### javascript/umd - - -Creates a [UMD](https://github.com/umdjs/umd) module of the style -dictionary. Name the module by adding a 'name' attribute on the file object -in your config. - -**Example** -```js -(function(root, factory) { - if (typeof module === "object" && module.exports) { - module.exports = factory(); - } else if (typeof exports === "object") { - exports["_styleDictionary"] = factory(); - } else if (typeof define === "function" && define.amd) { - define([], factory); - } else { - root["_styleDictionary"] = factory(); - } -}(this, function() { - return { - "color": { - "red": { - "value": "#FF0000" - } - } - }; -})) -``` - -* * * - -### javascript/es6 - - -Creates a ES6 module of the style dictionary. You can filter the style dictionary -to only export properties of a certain type by adding a 'filter' attribute on the -file object in the config. - -```json -{ - "platforms": { - "js": { - "files": [ - { - "format": "javascript/es6", - "destination": "colors.js", - "filter": { - "category": "color" - } - } - ] - } - } -} -``` - -**Example** -```js -export const BackgroundBase = '#ffffff'; -export const BackgroundAlt = '#fcfcfcfc'; -``` - -* * * - -### json - - -Creates a JSON file of the style dictionary. - -**Example** -```json -{ - "color": { - "base": { - "red": { - "value": "#ff000" - } - } - } -} -``` - -* * * - -### json/asset - - -Creates a JSON file of just the assets defined in the style dictionary. - -**Example** -```js -{ - "asset": { - "image": { - "logo": { - "value": "assets/logo.png" - } - } - } -} -``` - -* * * - -### sketch/palette - - -Creates a sketchpalette file of all the base colors - -**Example** -```json -{ - "compatibleVersion": "1.0", - "pluginVersion": "1.1", - "colors": [ - "#ffffff", - "#ff0000", - "#fcfcfc" - ] -} -``` - -* * * diff --git a/docs/index.html b/docs/index.html deleted file mode 100644 index a81773c3..00000000 --- a/docs/index.html +++ /dev/null @@ -1,72 +0,0 @@ - - - - - M5Stack Documentation - Style once, use everywhere. A build system for creating cross-platform styles. - - - - - - - - - - - - - - - - - - - - -
Loading...
- - - - - - - - - - - - diff --git a/docs/package_structure.md b/docs/package_structure.md deleted file mode 100644 index 5bf8c232..00000000 --- a/docs/package_structure.md +++ /dev/null @@ -1,120 +0,0 @@ -# Package Structure - -Style dictionaries are configuration driven. - -Here is a basic example of what a style dictionary package looks like. - -``` -├── config.json -├── properties/ -│ ├── size/ -│ ├── font.json -│ ├── color/ -│ ├── font.json -│ ... -├── assets/ -│ ├── fonts/ -│ ├── images/ -``` - - -## config.json -The default way is to use a config.json file in the root of your package. Here is a quick example: -```json -{ - "source": ["properties/**/*.json"], - "platforms": { - "scss": { - "transformGroup": "scss", - "prefix": "sd", - "buildPath": "build/scss/", - "files": [{ - "destination": "_variables.scss", - "format": "scss/variables" - }], - "actions": ["copy_assets"] - }, - "android": { - "transforms": ["attribute/cti", "name/cti/snake", "color/hex", "size/remToSp", "size/remToDp"], - "buildPath": "build/android/src/main/res/values/", - "files": [{ - "destination": "style_dictionary_colors.xml", - "template": "android/colors" - }] - } - } -} -``` - -| Attribute | Type | Description | -| :--- | :--- | :--- | -| source | Array[String] | An array of paths to JSON files that contain style properties. The Style Dictionary will do a deep merge of all of the JSON files so you can separate your properties into multiple files. | -| platforms | Object | An object containing platform config objects that describe how the Style Dictionary should build for that platform. You can add any arbitrary attributes on this object that will get passed to formats/templates and actions (more on these in a bit). This is useful for things like build paths, name prefixes, variable names, etc. | -| platform.transforms | Array[String] (optional) | An array of [transforms](transforms.md) to be performed on the style properties object. These will transform the properties in a non-desctructive way so each platform can transform the properties. Transforms to apply sequentially to all properties. Can be a built-in one or you can create your own. | -| platform.transformGroup | String (optional) | A string that maps to an array of transforms. This makes it easier to reference transforms by grouping them together. You must either define this or `transforms`. | -| platform.buildPath | String (optional) | Base path to build the files, must end with a trailing slash. | -| platform.files | Array (optional) | Files to be generated for this platform. | -| platform.file.destination | String (optional) | Location to build the file, will be appended to the buildPath. | -| platform.file.format | String (optional) | [Format](formats.md) used to generate the file. Can be a built-in one or you can create your own. Must declare a format or a template. | -| platform.file.template | String (optional) | [Template](templates.md) used to generate the file. Can be a built-in one or you can create your own. | -| platform.actions | Array[String] (optional) | [Actions](actions.md) to be performed after the files are built for that platform. Actions can be any arbitrary code you want to run like copying files, generating assets, etc. You can use pre-defined actions or create custom actions. | - ----- - -## Properties - -Style properties are a collection of JSON files. We usually keep them in a `properties` directory, but you can put them wherever you like, -they just need to be referenced in the `source` attribute on your `config.json` file. - -Style properties are what make up a style dictionary. You can structure your properties however you want to, the only requirement is the property contains a "value" attribute. This is how the build system knows which nodes are properties as opposed to structure. This allows you to have different levels of nesting. - -```json -{ - "color": { - "font": { - "base": { "value": "#111111" }, - "inverse": { - "base": { "value": "#EEEEEE" } - } - } - } -} -``` - -The above JSON snippet has 2 style properties, `color.font.base` and `color.font.inverse.base`. So you can have style properties defined at any level in the JSON structure. - -#### Category / Type / Item - -This is not required by any means, but we feel this classification structure of style properties makes the most sense semantically. Style properties can be organized into a hierarchical tree structure with the top level, category, defining the primitive nature of the property. For example, we have the color category and every property underneath is always a color. As you proceed down the tree, you get more specific about what that color is. Is it a background color, a text color, or a border color? What kind of text color is it? You get the point. It's like the animal kingdom classification: - -![](assets/cti.png) - -Now you can structure your property json files like simple objects: - -```json -{ - "size": { - "font": { - "base": { "value": "16" }, - "large": { "value": "20" } - } - } -} -``` - -The CTI is implicit in the structure, the category is 'size' and the type is 'font', and there are 2 properties 'base' and 'large'. - -Structuring style properties in this manner gives us consistent naming and accessing of these properties. You don't need to remember if it is button_color_error or error_button_color, it is color_background_button_error! - -You can organize and name your style properties however you want, there are no restrictions. But there are a good amount of helpers if you do use this structure, like the 'attribute/cti' transform which adds attributes to the property of its CTI based on the path in the object. There are a lot of name transforms as well for when you want a flat structure like for sass variables. - -Also, the CTI structure provides a good mechanism to target transforms for specific kinds of properties. All of the transforms provided by the framework use the CTI structure to know if it should be applied. For instance, the 'color/hex' transform only applies to properties of the category 'color'. - ----- - -## Assets - -Assets are not required, but can be useful to include in your style dictionary. If you don't want to manage having assets like images, -vectors, font files, etc. in multiple locations, you can keep them in your style dictionary as a single source of truth. - -> Coming soon: how to generate image assets based on your style dictionary diff --git a/docs/quick_start.md b/docs/quick_start.md deleted file mode 100644 index d603b20b..00000000 --- a/docs/quick_start.md +++ /dev/null @@ -1,216 +0,0 @@ -# Quick Start - -## Installation -*Note that you must have node (and npm) installed.* - -If you want to use the CLI, you can install it globally via npm: -```bash -$ npm install -g style-dictionary -``` - -!> Or you can install it like a normal npm dependency. This is a build tool so you are most likely going to want to save it as a dev dependency: -```bash -$ npm install -D style-dictionary -``` - -If you want to install it with yarn: -```bash -$ yarn add style-dictionary --dev -``` - -## Creating a New Project -The CLI comes with some starter code to get a new project started easily. -```bash -$ mkdir MyStyleD -$ cd MyStyleD -$ style-dictionary init basic -``` - -This command will copy over the example files found in example in this repo and then run the `style-dictionary build` command to generate the build artifacts. You should see something like this output: -``` -Reading config file from ./config.json -Building all platforms - -scss -✔︎ build/scss/_variables.scss - -android -✔︎ build/android/font_dimens.xml - -ios -✔︎ build/ios/StyleDictionaryColor.h -✔︎ build/ios/StyleDictionaryColor.m -``` - -Pat yourself on the back, you just built your first style dictionary! Take a look at what you built. This should have created a build directory and it should look like this: -``` -├── README.md -├── config.json -├── properties/ -│ ├── color/ -│ ├── base.json -│ ├── font.json -│ ├── size/ -│ ├── font.json -│ ├── font.json -├── build/ -│ ├── android/ -│ ├── font_dimens.xml -│ ├── colors.xml -│ ├── scss/ -│ ├── _variables.scss -│ ├── ios/ -│ ├── StyleDictionaryColor.h -│ ├── StyleDictionaryColor.m -``` - -If you open `config.json` you will see there are 3 platforms defined: scss, android, ios. Each platform has a transformGroup, buildPath, and files defined. The buildPath and files of the platform should match up to the files what were built. Those files should look like these: - -**Android** -```xml - - - 12.00sp - 16.00sp - 32.00sp - 16.00sp - - - - - #ffcccccc - #ff999999 - #ff111111 - #ff111111 - #ff999999 - #ffcccccc - -``` - -**SCSS** -```scss -$color-base-gray-light: rgb(204, 204, 204); -$color-base-gray-medium: rgb(153, 153, 153); -$color-base-gray-dark: rgb(17, 17, 17); -$color-font-base: rgb(17, 17, 17); -$color-font-secondary: rgb(153, 153, 153); -$color-font-tertiary: rgb(204, 204, 204); -$size-font-small: 0.75rem; -$size-font-medium: 1rem; -$size-font-large: 2rem; -$size-font-base: 1rem; -``` - -**iOS** -```objectivec -@implementation StyleDictionaryColor - -+ (UIColor *)color:(StyleDictionaryColorName)colorEnum{ - return [[self values] objectAtIndex:colorEnum]; -} - -+ (NSArray *)values { - static NSArray* colorArray; - static dispatch_once_t onceToken; - - dispatch_once(&onceToken, ^{ - colorArray = @[ -[UIColor colorWithRed:0.80f green:0.80f blue:0.80f alpha:1.0f], -[UIColor colorWithRed:0.60f green:0.60f blue:0.60f alpha:1.0f], -[UIColor colorWithRed:0.07f green:0.07f blue:0.07f alpha:1.0f], -[UIColor colorWithRed:0.07f green:0.07f blue:0.07f alpha:1.0f], -[UIColor colorWithRed:0.60f green:0.60f blue:0.60f alpha:1.0f], -[UIColor colorWithRed:0.80f green:0.80f blue:0.80f alpha:1.0f] - ]; - }); - - return colorArray; -} - -@end -``` - -Pretty nifty! This shows a few things happening: -1. The build system does a deep merge of all the property JSON files defined in the `source` attribute of `config.json`. This allows you to split up the property JSON files however you want. There are 2 JSON files with `color` as the top level key, but they get merged properly. -1. The build system resolves references to other style properties. `{size.font.medium.value}` gets resolved properly -1. The build system handles references to property values in other files as well as you can see in `properties/color/font.json` -1. Values get transformed differently depending on the platform they are built to - - -## Making a change - -Now lets make a change and see how that affects things. Open up `properties/color/base.json` and change `"#111111"` to `"#000000"`. After you make that change, save the file and re-run the build command `style-dictionary build`. Open up the build files and take a look. Now - -**Android** -```xml - - - #ffcccccc - #ff999999 - #ff000000 - #ff111111 - #ff999999 - #ffcccccc - -``` -```scss -$color-base-gray-light: rgb(204, 204, 204); -$color-base-gray-medium: rgb(153, 153, 153); -$color-base-gray-dark: rgb(0, 0, 0); -$color-font-base: rgb(0, 0, 0); -$color-font-secondary: rgb(153, 153, 153); -$color-font-tertiary: rgb(204, 204, 204); -``` -```objectivec -[UIColor colorWithRed:0.80f green:0.80f blue:0.80f alpha:1.00f], -[UIColor colorWithRed:0.60f green:0.60f blue:0.60f alpha:1.00f], -[UIColor colorWithRed:0.00f green:0.00f blue:0.00f alpha:1.00f], -[UIColor colorWithRed:0.00f green:0.00f blue:0.00f alpha:1.00f], -[UIColor colorWithRed:0.60f green:0.60f blue:0.60f alpha:1.00f], -[UIColor colorWithRed:0.80f green:0.80f blue:0.80f alpha:1.00f] -``` - -That's it! There is a lot more you can do with your style dictionary than just generate some files with color values. Take a look -at some [examples](examples.md) or take a deeper dive into [package structure](package_structure.md), [extending](extending.md), or how the [build process](build_process.md) works. - -## Basic Usage -### CLI -```bash -$ style-dictionary build -``` -Call this in the root directory of your project. The only thing needed is a `config.json` file. There are also arguments: - -| Flag | Short Flag | Description | -| --- | --- | --- | -| --config \[path\] | -h | Set the config file to use. Must be a .json file | -| --platform \[platform\] | -p | Only build a specific platform defined in the config file. | -| --help | -h | Display help content | -| --version | -v | Display the version | - -### Node -You can also use the style dictionary build system in node if you want to [extend](extending.md) the functionality or use it in another build system like Grunt or Gulp. -```javascript -const StyleDictionary = require('style-dictionary').extend('config.json'); - -StyleDictionary.buildAllPlatforms(); -``` - -The `.extend()` method is an overloaded method that can also take an object with the configuration in the same format as a config.json file. -```javascript -const StyleDictionary = require('style-dictionary').extend({ - source: ['properties/**/*.json'], - platforms: { - scss: { - transformGroup: 'scss', - buildPath: 'build/', - files: [{ - destination: 'variables.scss', - format: 'scss/variables' - }] - } - // ... - } -}); - -StyleDictionary.buildAllPlatforms(); -``` diff --git a/docs/templates.md b/docs/templates.md deleted file mode 100644 index 1ed518e5..00000000 --- a/docs/templates.md +++ /dev/null @@ -1,296 +0,0 @@ -# Templates - -Templates are one of the ways to create files that act as interfaces for your style dictionary. For example, you want to be able to -use your style dictionary in Android. You can use the `android/colors` template which will create an Anroid resource XML file from -your style dictionary. You can define custom templates with the [`registerTemplate`](api.md#registertemplate). - -Templates and Formats serve the same purpose: use your style dictionary as data to build a file. You use templates in your config -file under platforms > [platform] > files > [file] - -```json -{ - "source": ["properties/**/*.json"], - "platforms": { - "android": { - "transformGroup": "android", - "files": [ - { - "template": "android/colors", - "destination": "colors.xml" - } - ] - } - } -} -``` - ->*__How are Templates different than Formats?__* - ->Mainly syntactic sugar; anything you can do in a Template you can do in a Format. Use whichever is easier for you to write. We find -that Templates are good if you have a lot of boilerplate code around where the style dictionary will go (like writing ObjectiveC files). -Formats are better if there is little to no boilerplate code like a flat SCSS variables file. - -### Using a different templating language - -If you are partial to Handlebars or some other templating language, anything will work as long as there is a node module for it. -All you need to do is register a custom format which calls your template and returns a string. Here is a quick example for Handlebars. - -```js -const StyleDictionary = require('style-dictionary').extend('config.json'); -const Handlebars = require('handlebars'); - -const template = Handlebars.compile( fs.readFileSync('templates/MyTemplate.hbs') ); - -styleDictionary.registerFormat({ - name: 'myTemplate', - formatter: function(dictionary, platform) { - return template({ - properties: dictionary.properties, - options: platform - }); - } -}); - -styleDictionary.buildAllPlatforms(); -``` - ----- - -## Pre-defined Templates - -[lib/common/templates.js](https://github.com/amzn/style-dictionary/blob/master/lib/common/templates.js) - -### android/colors - - -Creates a color resource xml file with all the colors in your style dictionary. - -**Example** -```xml - - - #fffaf3f2 - #fff0cccc - #ffe19d9c -``` - -* * * - -### android/dimens - - -Creates a dimen resource xml file with all the sizes in your style dictionary. - -**Example** -```xml - - - 5.00dp - 10.00dp - 15.00dp -``` - -* * * - -### android/fontDimens - - -Creates a dimen resource xml file with all the font sizes in your style dictionary. - -**Example** -```xml - - - 10.00sp - 13.00sp - 15.00sp -``` - -* * * - -### android/integers - - -Creates a resource xml file with all the integers in your style dictionary. It filters your -style properties by `prop.attributes.category === 'time'` - -**Todo** - -- Update the filter on this. - -**Example** -```xml - - - 1000 - 2000 - 4000 -``` - -* * * - -### android/strings - - -Creates a resource xml file with all the strings in your style dictionary. Filters your -style properties by `prop.attributes.category === 'content'` - -**Example** -```xml - - - - - -``` - -* * * - -### ios/macros - - -Creates an Objective-C header file with macros for style properties - -**Example** -```objectivec -#import -#import - -#define ColorFontLink [UIColor colorWithRed:0.00f green:0.47f blue:0.80f alpha:1.00f] -#define SizeFontTiny 176.00f -``` - -* * * - -### ios/plist - - -Creates an Objective-C plist file - -**Todo** - -- Fix this template and add example and usage - - -* * * - -### ios/singleton.m - - -Creates an Objective-C implementation file of a style dictionary singleton class - -**Todo** - -- Add example and usage - - -* * * - -### ios/singleton.h - - -Creates an Objective-C header file of a style dictionary singleton class - -**Todo** - -- Add example and usage - - -* * * - -### ios/static.h - - -Creates an Objective-C header file of a static style dictionary class - -**Todo** - -- Add example and usage - - -* * * - -### ios/static.m - - -Creates an Objective-C implementation file of a static style dictionary class - -**Todo** - -- Add example and usage - - -* * * - -### ios/colors.h - - -Creates an Objective-C header file of a color class - -**Todo** - -- Add example and usage - - -* * * - -### ios/colors.m - - -Creates an Objective-C implementation file of a color class - -**Todo** - -- Add example and usage - - -* * * - -### ios/strings.h - - -Creates an Objective-C header file of strings - -**Todo** - -- Add example and usage - - -* * * - -### ios/strings.m - - -Creates an Objective-C implementation file of strings - -**Todo** - -- Add example and usage - - -* * * - -### css/fonts.css - - -Creates CSS file with @font-face declarations - -**Todo** - -- Add example and usage - - -* * * - -### static-style-guide/index.html - - -Creates a generic static html page - -**Todo** - -- Add example and usage - - -* * * - diff --git a/docs/transform_groups.md b/docs/transform_groups.md deleted file mode 100644 index 9f38f8e4..00000000 --- a/docs/transform_groups.md +++ /dev/null @@ -1,118 +0,0 @@ -# Transform Groups - -Transform Groups are a way to easily define and use groups of transforms. They are an array of transforms. You can define custom transform groups with the [`registerTransformGroup`](api.md#registertransformgroup). - -You use transformGroups in your config file under platforms > [platform] > transformGroup - -```json -{ - "source": ["properties/**/*.json"], - "platforms": { - "android": { - "transformGroup": "android" - } - } -} -``` - ----- - -## Pre-defined Transform groups - -[lib/common/transformGroups.js](https://github.com/amzn/style-dictionary/blob/master/lib/common/transformGroups.js) - -### web - - -Transforms: - -[attribute/cti](transforms.md#attributecti) -[name/cti/kebab](transforms.md#namectikebab) -[size/px](transforms.md#sizepx) -[color/css](transforms.md#colorcss) - - -* * * - -### scss - - -Transforms: - -[attribute/cti](transforms.md#attributecti) -[name/cti/kebab](transforms.md#namectikebab) -[time/seconds](transforms.md#timeseconds) -[content/icon](transforms.md#contenticon) -[size/rem](transforms.md#sizerem) -[color/css](transforms.md#colorcss) - - -* * * - -### less - - -Transforms: - -[attribute/cti](transforms.md#attributecti) -[name/cti/kebab](transforms.md#namectikebab) -[time/seconds](transforms.md#timeseconds) -[content/icon](transforms.md#contenticon) -[size/rem](transforms.md#sizerem) -[color/hex](transforms.md#colorhex) - - -* * * - -### html - - -Transforms: - -[attribute/cti](transforms.md#attributecti) -[attribute/color](transforms.md#attributecolor) -[name/human](transforms.md#namehuman) - - -* * * - -### android - - -Transforms: - -[attribute/cti](transforms.md#attributecti) -[name/cti/snake](transforms.md#namectisnake) -[color/hex8android](transforms.md#colorhex8android) -[size/remToSp](transforms.md#sizeremtosp) -[size/remToDp](transforms.md#sizeremtodp) - - -* * * - -### ios - - -Transforms: - -[attribute/cti](transforms.md#attributecti) -[name/cti/pascal](transforms.md#namectipascal) -[color/UIColor](transforms.md#coloruicolor) -[content/objC/literal](transforms.md#contentobjcliteral) -[asset/objC/literal](transforms.md#assetobjcliteral) -[size/remToPt](transforms.md#sizeremtopt) -[font/objC/literal](transforms.md#fontobjcliteral) - - -* * * - -### assets - - -Transforms: - -[attribute/cti](transforms.md#attributecti) - - -* * * - diff --git a/docs/transforms.md b/docs/transforms.md deleted file mode 100644 index 49c70d91..00000000 --- a/docs/transforms.md +++ /dev/null @@ -1,485 +0,0 @@ -# Transforms - -Transforms are functions that transform a property so that each platform can consume the property in different ways. A simple example is changing pixel values to point values for iOS and dp or sp for Android. Transforms are applied in a non-destructive way so each platform can transform the properties. Transforms are performed sequentially, so the order you use transforms matters. You can define custom transforms with the [`registerTransform`](api.md#registertransform). - -You use transforms in your config file under platforms > [platform] > transforms - -```json -{ - "source": ["properties/**/*.json"], - "platforms": { - "android": { - "transforms": ["attribute/cti", "name/cti/kebab", "color/hex", "size/rem"] - } - } -} -``` - -A transform consists of 4 parts: type, name, matcher, and transformer. Transforms are run on all properties where the matcher returns true. *NOTE: if you don't provide a matcher function, it will match all properties.* - -### Transform Types -There are 3 types of transforms: attribute, name, and value. - -**Attribute:** An attribute transform adds to the attributes object on a property. This is for including any meta-data about a property such as it's CTI or other information. - -**Name:** A name transform transform the name of a property. You should really only be apply one name transformer because they will override each other if you use more than one. - -**Value:** The value transform is the most important as this is the one that changes the representation of the value. Colors can be turned into hex values, rgb, hsl, hsv, etc. Value transforms have a matcher function so that they only get run on certain properties. This allows us to only run a color transform on just the colors and not every property. - ----- - -## Pre-defined Transforms - -[lib/common/transforms.js](https://github.com/amzn/style-dictionary/blob/master/lib/common/transforms.js) - -> All the pre-defined transforms included use the [CTI structure](package_structure.md#properties) for the match properties. If you structure your style properties differently you will need to write [custom transforms](#custom-transforms) or make sure the property CTIs are on the attributes of your properties. - -### attribute/cti - - -Adds: category, type, item, subitem, and state on the attributes object based on the location in the style dictionary. - -```js -// Matches: all -// Returns: -{ - "category": "color", - "type": "background", - "item": "button", - "subitem": "primary", - "state": "active" -} -``` - - -* * * - -### attribute/color - - -Adds: hex, hsl, hsv, rgb, red, blue, green. - -```js -// Matches: prop.attributes.category === 'color' -// Returns -{ - "hex": "009688", - "rgb": {"r": 0, "g": 150, "b": 136, "a": 1}, - "hsl": {"h": 174.4, "s": 1, "l": 0.294, "a": 1}, - "hsv": {"h": 174.4, "s": 1, "l": 0.588, "a": 1}, -} -``` - - -* * * - -### name/human - - -Creates a human-friendly name - -```js -// Matches: All -// Returns: -"button primary" -``` - - -* * * - -### name/cti/camel - - -Creates a camel case name. If you define a prefix on the platform in your config, it will prepend with your prefix - -```js -// Matches: all -// Returns: -"colorBackgroundButtonPrimaryActive" -"prefixColorBackgroundButtonPrimaryActive" -``` - - -* * * - -### name/cti/kebab - - -Creates a kebab case name. If you define a prefix on the platform in your config, it will prepend with your prefix - -```js -// Matches: all -// Returns: -"color-background-button-primary-active" -"prefix-color-background-button-primary-active" -``` - - -* * * - -### name/cti/snake - - -Creates a snake case name. If you define a prefix on the platform in your config, it will prepend with your prefix - -```js -// Matches: all -// Returns: -"color_background_button_primary_active" -"prefix_color_background_button_primary_active" -``` - - -* * * - -### name/cti/constant - - -Creates a constant-style name based on the full CTI of the property. If you define a prefix on the platform in your config, it will prepend with your prefix - -```js -// Matches: all -// Returns: -"COLOR_BACKGROUND_BUTTON_PRIMARY_ACTIVE" -"PREFIX_COLOR_BACKGROUND_BUTTON_PRIMARY_ACTIVE" -``` - - -* * * - -### name/ti/constant - - -Creates a constant-style name on just the type and item of the property. This is useful if you want to create different static classes/files for categories like `Color.BACKGROUND_BASE`. If you define a prefix on the platform in your config, it will prepend with your prefix. - -```js -// Matches: all -// Returns: -"BACKGROUND_BUTTON_PRIMARY_ACTIVE" -"PREFIX_BACKGROUND_BUTTON_PRIMARY_ACTIVE" -``` - - -* * * - -### name/cti/pascal - - -Creates a Pascal case name. If you define a prefix on the platform in your config, it will prepend with your prefix - -```js -// Matches: all -// Returns: -"ColorBackgroundButtonPrimaryActive" -"PrefixColorBackgroundButtonPrimaryActive" -``` - - -* * * - -### color/rgb - - -Transforms the value into an RGB string - -```js -// Matches: prop.attributes.category === 'color' -// Returns: -"rgb(0, 150, 136)" -``` - - -* * * - -### color/hex - - -Transforms the value into an 6-digit hex string - -```js -// Matches: prop.attributes.category === 'color' -// Returns: -"#009688" -``` - - -* * * - -### color/hex8 - - -Transforms the value into an 8-digit hex string - -```js -// Matches: prop.attributes.category === 'color' -// Returns: -"#009688ff" -``` - - -* * * - -### color/hex8android - - -Transforms the value into an 8-digit hex string for Android because they put the alpha channel first - -```js -// Matches: prop.attributes.category === 'color' -// Returns: -"#ff009688" -``` - - -* * * - -### color/UIColor - - -Transforms the value into an UIColor class for iOS - -```objectivec -// Matches: prop.attributes.category === 'color' -// Returns: -[UIColor colorWithRed:0.00f green:0.59f blue:0.53f alpha:1.0f] -``` - - -* * * - -### color/css - - -Transforms the value into a hex or rgb string depending on if it has transparency - -```css -// Matches: prop.attributes.category === 'color' -// Returns: -#000000 -rgba(0,0,0,0.5) -``` - - -* * * - -### size/sp - - -Transforms the value into a scale-independent pixel (sp) value for font sizes on Android. It will not scale the number. - -```js -// Matches: prop.attributes.category === 'size' && prop.attributes.type === 'font' -// Returns: -"10.0sp" -``` - - -* * * - -### size/dp - - -Transforms the value into a density-independent pixel (dp) value for non-font sizes on Android. It will not scale the number. - -```js -// Matches: prop.attributes.category === 'size' && prop.attributes.type !== 'font' -// Returns: -"10.0dp" -``` - - -* * * - -### size/remToSp - - -Transforms the value from a REM size on web into a scale-independent pixel (sp) value for font sizes on Android. It WILL scale the number by a factor of 16 (common base font size on web). - -```js -// Matches: prop.attributes.category === 'size' && prop.attributes.type === 'font' -// Returns: -"16.0sp" -``` - - -* * * - -### size/remToDp - - -Transforms the value from a REM size on web into a density-independent pixel (dp) value for font sizes on Android. It WILL scale the number by a factor of 16 (common base font size on web). - -```js -// Matches: prop.attributes.category === 'size' && prop.attributes.type !== 'font' -// Returns: -"16.0dp" -``` - - -* * * - -### size/px - - -Adds 'px' to the end of the number. Does not scale the number - -```js -// Matches: prop.attributes.category === 'size' -// Returns: -"10px" -``` - - -* * * - -### size/rem - - -Adds 'rem' to the end of the number. Does not scale the number - -```js -// Matches: prop.attributes.category === 'size' -// Returns: -"10rem" -``` - - -* * * - -### size/remToPt - - -Scales the number by 16 (default web font size) and adds 'pt' to the end. - -```js -// Matches: prop.attributes.category === 'size' -// Returns: -"16pt" -``` - - -* * * - -### size/remToPx - - -Scales the number by 16 (default web font size) and adds 'px' to the end. - -```js -// Matches: prop.attributes.category === 'size' -// Returns: -"16px" -``` - - -* * * - -### content/icon - - -Takes a unicode point and transforms it into a form CSS can use. - -```js -// Matches: prop.attributes.category === 'content' && prop.attributes.type === 'icon' -// Returns: -"'\\E001'" -``` - - -* * * - -### content/quote - - -Wraps the value in a single quoted string - -```js -// Matches: prop.attributes.category === 'content' -// Returns: -"'string'" -``` - - -* * * - -### content/objC/literal - - -Wraps the value in a double-quoted string and prepends an '@' to make a string literal. - -```objectivec -// Matches: prop.attributes.category === 'content' -// Returns: - -**"string"**: ``` - -* * * - -### font/objC/literal - - -Wraps the value in a double-quoted string and prepends an '@' to make a string literal. - -```objectivec -// Matches: prop.attributes.category === 'font' -// Returns: @"string" -``` - - -* * * - -### time/seconds - - -Assumes a time in miliseconds and transforms it into a decimal - -```js -// Matches: prop.attributes.category === 'time' -// Returns: -"0.5s" -``` - - -* * * - -### asset/base64 - - -Wraps the value in a double-quoted string and prepends an '@' to make a string literal. - -```js -// Matches: prop.attributes.category === 'asset' -// Returns: -'IyBlZGl0b3Jjb25maWcub3JnCnJvb3QgPSB0cnVlCgpbKl0KaW5kZW50X3N0eWxlID0gc3BhY2UKaW5kZW50X3NpemUgPSAyCmVuZF9vZl9saW5lID0gbGYKY2hhcnNldCA9IHV0Zi04CnRyaW1fdHJhaWxpbmdfd2hpdGVzcGFjZSA9IHRydWUKaW5zZXJ0X2ZpbmFsX25ld2xpbmUgPSB0cnVlCgpbKi5tZF0KdHJpbV90cmFpbGluZ193aGl0ZXNwYWNlID0gZmFsc2U=' -``` - - -* * * - -### asset/path - - -Prepends the local file path - -```js -// Matches: prop.attributes.category === 'asset' -// Returns: -"path/to/file/asset.png" -``` - - -* * * - -### asset/objC/literal - - -Wraps the value in a double-quoted string and prepends an '@' to make a string literal. - -```objectivec -// Matches: prop.attributes.category === 'asset' -// Returns: @"string" -``` - - -* * * - diff --git a/en/COPYRIGHT.rst b/en/COPYRIGHT.rst new file mode 100644 index 00000000..d7f2f3a1 --- /dev/null +++ b/en/COPYRIGHT.rst @@ -0,0 +1,74 @@ +Copyrights and Licenses +*********************** + +Software Copyrights +=================== + +All original source code in this repository is Copyright (C) 2017-2018 M5Stack Inc. This source code is licensed under the Apache License 2.0 as described in the file LICENSE. + +Additional third party copyrighted code is included under the following licenses. + +Where source code headers specify Copyright & License information, this information takes precedence over the summaries made here. + +Firmware Components +------------------- + + + +Build Tools +----------- + +This is the list of licenses for tools included in this repository, which are used to build applications. The tools do not become part of the application (firmware), so their license does not affect licensing of the application. + + +Xtensa libhal MIT License +========================= + +Copyright (c) 2003, 2006, 2010 Tensilica Inc. + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +TinyBasic Plus MIT License +========================== + +Copyright (c) 2012-2013 + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +TJpgDec License +=============== + +TJpgDec - Tiny JPEG Decompressor R0.01 (C)ChaN, 2011 +The TJpgDec is a generic JPEG decompressor module for tiny embedded systems. +This is a free software that opened for education, research and commercial +developments under license policy of following terms. + +Copyright (C) 2011, ChaN, all right reserved. + +* The TJpgDec module is a free software and there is NO WARRANTY. +* No restriction on use. You can use, modify and redistribute it for personal, non-profit or commercial products UNDER YOUR RESPONSIBILITY. +* Redistributions of source code must retain the above copyright notice. + + + diff --git a/en/Makefile b/en/Makefile new file mode 100644 index 00000000..65ea7b92 --- /dev/null +++ b/en/Makefile @@ -0,0 +1,30 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = M5Stack +SOURCEDIR = en +BUILDDIR = en_build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(en)/" "../$(BUILDDIR)" $(SPHINXOPTS) $(O) + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +clean: + rm -rf ../$(BUILDDIR)/* + +.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 $@ "$(en)" "../$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/en/about.rst b/en/about.rst new file mode 100644 index 00000000..2c460675 --- /dev/null +++ b/en/about.rst @@ -0,0 +1,16 @@ +About +===== + +This is documentation of `ESP-IDF `_, the framework to develop applications for `ESP32 `_ chip by `Espressif `_. + +The ESP32 is 2.4 GHz Wi-Fi and Bluetooth combo, 32 bit dual core chip with 600 DMIPS processing power. + +.. figure:: ../_static/about-doc.png + :align: center + :alt: Espressif IoT Integrated Development Framework + :figclass: align-center + + Espressif IoT Integrated Development Framework + +The ESP-IDF, Espressif IoT Integrated Development Framework, provides toolchain, API, components and workflows to develop applications for ESP32 using Windows, Linux and Mac OS operating systems. + diff --git a/en/api-reference/index.rst b/en/api-reference/index.rst new file mode 100644 index 00000000..2a38c53b --- /dev/null +++ b/en/api-reference/index.rst @@ -0,0 +1,10 @@ +************* +API Reference +************* + +.. toctree:: + :maxdepth: 1 + + LCD + + diff --git a/en/api-reference/lcd/Backup/lcd_api_arduino.md b/en/api-reference/lcd/Backup/lcd_api_arduino.md new file mode 100644 index 00000000..d104da12 --- /dev/null +++ b/en/api-reference/lcd/Backup/lcd_api_arduino.md @@ -0,0 +1,66 @@ +##LCD API for Arduino +### Overview + + + +### API Reference +#### 1.LCD(spi=spi) +***Description:*** +initialize the lcd (fgcolor: white, bgcolor: black) +***Parament:*** +***Example:*** +```python +from machine import SPI, Pin +from display import LCD +spi = SPI(1, baudrate=32000000, mosi=Pin(23), miso=Pin(19), sck=Pin(18)) +lcd = LCD(spi = spi) +``` + +#### 2.lcd.drawPixel(x, y [,color]) +***Description:*** +Draw the pixel at position (x,y). +If color is not given, current foreground color is used. +***Parament:*** +***Example:*** +```python +#The M5Stack Core LCD has been initialized +lcd.drawPixel(11, 22, LCD.ORANGE) +``` + +#### 3.lcd.fillScreen(lcd.color565(r, g, b)) +***Description:*** +draw the pixel at position (x,y) +*Note:* if color is not given, current foreground color is used +***Parament:*** +***Example:*** +```python +#The M5Stack Core LCD has been initialized +lcd.fillScreen(lcd.color565(0x00, 0x00, 0x00)) +``` + +#### 4.lcd.circle(x, y, r [,color, fillcolor]) +***Description:*** +draw the pixel at position (x,y) +*Note:* if color is not given, current foreground color is used. if fillcolor is given, filled circle will be drawn +***Parament:*** +***r:*** the radius of circle +***Example:*** +```python +#The M5Stack Core LCD has been initialized +lcd.circle(100,100,10,lcd.BLUE) +``` + +### Usage +```python +from machine import SPI, Pin +from display import LCD + +spi = SPI(1, baudrate=32000000, mosi=Pin(23), miso=Pin(19), sck=Pin(18)) + +lcd = LCD(spi = spi) +lcd.fillScreen(lcd.color565(0x00, 0x00, 0x00)) +lcd.line(0,0,44,44,lcd.ORANGE) +lcd.triangle(22,22,69,98,51,22,lcd.RED) +lcd.circle(100,100,10,lcd.BLUE) +lcd.print('LLLLLLLL',80,80) +``` \ No newline at end of file diff --git a/en/api-reference/lcd/Backup/lcd_api_arduino.rst b/en/api-reference/lcd/Backup/lcd_api_arduino.rst new file mode 100644 index 00000000..bcb3da87 --- /dev/null +++ b/en/api-reference/lcd/Backup/lcd_api_arduino.rst @@ -0,0 +1,75 @@ +LCD API for Arduino +------------------- + +Overview +~~~~~~~~ + +API Reference +~~~~~~~~~~~~~ + +1.LCD(spi=spi) +^^^^^^^^^^^^^^ + +***Description:*** initialize the lcd (fgcolor: white, bgcolor: black) +***Parament:*** ***Example:*** + +.. code:: python + + from machine import SPI, Pin + from display import LCD + spi = SPI(1, baudrate=32000000, mosi=Pin(23), miso=Pin(19), sck=Pin(18)) + lcd = LCD(spi = spi) + +2.lcd.drawPixel(x, y [,color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** Draw the pixel at position (x,y). If color is not +given, current foreground color is used. ***Parament:*** ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.drawPixel(11, 22, LCD.ORANGE) + +3.lcd.fillScreen(lcd.color565(r, g, b)) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** draw the pixel at position (x,y) *Note:* if color is +not given, current foreground color is used ***Parament:*** +***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.fillScreen(lcd.color565(0x00, 0x00, 0x00)) + +4.lcd.circle(x, y, r [,color, fillcolor]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** draw the pixel at position (x,y) *Note:* if color is +not given, current foreground color is used. if fillcolor is given, +filled circle will be drawn ***Parament:*** ***r:*** the radius of +circle ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.circle(100,100,10,lcd.BLUE) + +Usage +~~~~~ + +.. code:: python + + from machine import SPI, Pin + from display import LCD + + spi = SPI(1, baudrate=32000000, mosi=Pin(23), miso=Pin(19), sck=Pin(18)) + + lcd = LCD(spi = spi) + lcd.fillScreen(lcd.color565(0x00, 0x00, 0x00)) + lcd.line(0,0,44,44,lcd.ORANGE) + lcd.triangle(22,22,69,98,51,22,lcd.RED) + lcd.circle(100,100,10,lcd.BLUE) + lcd.print('LLLLLLLL',80,80) + diff --git a/en/api-reference/lcd/Backup/lcd_api_micropython.md b/en/api-reference/lcd/Backup/lcd_api_micropython.md new file mode 100644 index 00000000..24c3f24c --- /dev/null +++ b/en/api-reference/lcd/Backup/lcd_api_micropython.md @@ -0,0 +1,66 @@ +##LCD API for Micropython +### Overview + + + +### API Reference +#### 1.LCD(spi=spi) +***Description:*** +initialize the lcd (fgcolor: white, bgcolor: black) +***Parament:*** +***Example:*** +```python +from machine import SPI, Pin +from display import LCD +spi = SPI(1, baudrate=32000000, mosi=Pin(23), miso=Pin(19), sck=Pin(18)) +lcd = LCD(spi = spi) +``` + +#### 2.lcd.drawPixel(x, y [,color]) +***Description:*** +Draw the pixel at position (x,y). +If color is not given, current foreground color is used. +***Parament:*** +***Example:*** +```python +#The M5Stack Core LCD has been initialized +lcd.drawPixel(11, 22, LCD.ORANGE) +``` + +#### 3.lcd.fillScreen(lcd.color565(r, g, b)) +***Description:*** +draw the pixel at position (x,y) +*Note:* if color is not given, current foreground color is used +***Parament:*** +***Example:*** +```python +#The M5Stack Core LCD has been initialized +lcd.fillScreen(lcd.color565(0x00, 0x00, 0x00)) +``` + +#### 4.lcd.circle(x, y, r [,color, fillcolor]) +***Description:*** +draw the pixel at position (x,y) +*Note:* if color is not given, current foreground color is used. if fillcolor is given, filled circle will be drawn +***Parament:*** +***r:*** the radius of circle +***Example:*** +```python +#The M5Stack Core LCD has been initialized +lcd.circle(100,100,10,lcd.BLUE) +``` + +### Usage +```python +from machine import SPI, Pin +from display import LCD + +spi = SPI(1, baudrate=32000000, mosi=Pin(23), miso=Pin(19), sck=Pin(18)) + +lcd = LCD(spi = spi) +lcd.fillScreen(lcd.color565(0x00, 0x00, 0x00)) +lcd.line(0,0,44,44,lcd.ORANGE) +lcd.triangle(22,22,69,98,51,22,lcd.RED) +lcd.circle(100,100,10,lcd.BLUE) +lcd.print('LLLLLLLL',80,80) +``` \ No newline at end of file diff --git a/en/api-reference/lcd/Backup/lcd_api_micropython.rst b/en/api-reference/lcd/Backup/lcd_api_micropython.rst new file mode 100644 index 00000000..927b5906 --- /dev/null +++ b/en/api-reference/lcd/Backup/lcd_api_micropython.rst @@ -0,0 +1,75 @@ +LCD API for Micropython +----------------------- + +Overview +~~~~~~~~ + +API Reference +~~~~~~~~~~~~~ + +1.LCD(spi=spi) +^^^^^^^^^^^^^^ + +***Description:*** initialize the lcd (fgcolor: white, bgcolor: black) +***Parament:*** ***Example:*** + +.. code:: python + + from machine import SPI, Pin + from display import LCD + spi = SPI(1, baudrate=32000000, mosi=Pin(23), miso=Pin(19), sck=Pin(18)) + lcd = LCD(spi = spi) + +2.lcd.drawPixel(x, y [,color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** Draw the pixel at position (x,y). If color is not +given, current foreground color is used. ***Parament:*** ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.drawPixel(11, 22, LCD.ORANGE) + +3.lcd.fillScreen(lcd.color565(r, g, b)) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** draw the pixel at position (x,y) *Note:* if color is +not given, current foreground color is used ***Parament:*** +***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.fillScreen(lcd.color565(0x00, 0x00, 0x00)) + +4.lcd.circle(x, y, r [,color, fillcolor]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** draw the pixel at position (x,y) *Note:* if color is +not given, current foreground color is used. if fillcolor is given, +filled circle will be drawn ***Parament:*** ***r:*** the radius of +circle ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.circle(100,100,10,lcd.BLUE) + +Usage +~~~~~ + +.. code:: python + + from machine import SPI, Pin + from display import LCD + + spi = SPI(1, baudrate=32000000, mosi=Pin(23), miso=Pin(19), sck=Pin(18)) + + lcd = LCD(spi = spi) + lcd.fillScreen(lcd.color565(0x00, 0x00, 0x00)) + lcd.line(0,0,44,44,lcd.ORANGE) + lcd.triangle(22,22,69,98,51,22,lcd.RED) + lcd.circle(100,100,10,lcd.BLUE) + lcd.print('LLLLLLLL',80,80) + diff --git a/en/api-reference/lcd/index.rst b/en/api-reference/lcd/index.rst new file mode 100644 index 00000000..2ac59d63 --- /dev/null +++ b/en/api-reference/lcd/index.rst @@ -0,0 +1,308 @@ +LCD API +******** + +----------------------------- + +Function +--------- + +lcd.setRotation(degree) +>>>>>>>>>>>>>>>>>>>>>>> + +| **Description:** +| set the angle of rotation of the entire screen + +| **Parament:** +| **degree:** the angle of rotation + +| **Example:** +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.setRotation(90) + +lcd.setColor(color [, background\_color]) +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +| **Description:** 　　 +| Set the default foreground/background color + +| **Parament:** +| **color:** the color of text +| **background\_color:** the fill color of text + +| **Example:** +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.setColor(lcd.RED) + lcd.setColor(lcd.ORANGE, LCD.DARKCYAN) + +lcd.setTextColor(color [,background\_color]) +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +| **Description:** 　　 +| This function is as same as *setColor(color [, background\_color])* + +| **Example:** +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.setTextColor(lcd.PINK) + lcd.setTextColor(lcd.ORANGE, LCD.DARKCYAN) + +lcd.fillScreen(color) +>>>>>>>>>>>>>>>>>>>>>>> + +| **Description:** 　　 +| Fill the entire screen with the given color + +| **Parament:** +| **color:** color values + +| **Example:** +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.fillScreen(lcd.RED) + +lcd.drawPixel(x, y [,color]) +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +| **Description:** 　　 +| Draw the pixel at position **(x,y)** +| *Note:* +| *If color is not given, current foreground color is used* + +| **Parament:** +| **color：** color values + +| **Example:** +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.drawPixel(22,22,lcd.RED)   + +lcd.drawLine(x, y, x1, y1 [,color]) +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +| **Description:** 　　 +| Draw the line from point **(x,y)** to point **(x1,y1)** +| *Note:* +| *If color is not given, current foreground color is used* + +| **Parament:** +| **color：** color values + +| **Example:** +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.drawLine(0,0,12,12,lcd.WHITE)  + +lcd.drawTriangle(x, y, x1, y1, x2, y2 [,color]) +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +| **Description:** 　　 +| Draw the triangel between points **(x,y)**, **(x1,y1)** and **(x2,y2)** +| *Note:* 　　 +| If color is not given, current foreground color is used +　 +| **Parament:** +| **color:** color values + +| **Example:** +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.drawTriangle(22,22,69,98,51,22,lcd.RED) + +lcd.fillTriangle(x, y, x1, y1, x2, y2 [,color]) +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +| **Description:** 　　 +| Fill the triangel between points **(x,y)**, **(x1,y1)** and **(x2,y2)** +| *Note:* 　　 +| *If color is not given, triangle will be filled in current foreground color* + +| **Parament:** +| **color：** color values + +| **Example:** +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.fillTriangle(122, 122, 169, 198, 151, 182, lcd.RED) + +lcd.drawCircle(x, y, r [,color]) +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> +| **Description:*** 　　 +| Draw the circle with center at **(x,y)** and radius **r** +| *Note:* 　　 +| *If color is not given, current foreground color is used* + +| **Parament:** +| **r:** the radius of circle +| **color:** color values + +| **Example:** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.drawCircle(180, 180, 10, lcd.BLUE)  + +lcd.fillCircle(x, y, r [,color]) +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +| **Description:** 　　 +| Fill the circle with center at **(x,y)** and radius **r** +| *Note:* 　　 +| *If color is not given, current foregroundcolor will be used* + +| **Parament:** +| **r:** the radius of circle +| **color:** color values + +| **Example:** +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.fillcircle(100, 100, 10, lcd.BLUE)  + +lcd.drawRect(x, y, w, h, [,color]) +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +| **Description:** 　　 +| Draw the rectangle from the upper left point at **(x,y)** and **width** and **height** +| *Note:* 　　 +| *If color is not given, rectangle will be drawn in current foreground color* + +| **Parament:** +| **w:** display phisical width in pixels (display's smaller dimension) +| **h:** display phisical height in pixels (display's larger dimension) +| **color:** optional, color values + +| **Example:** +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.drawRect(180, 12, 122, 10, lcd.BLUE) + +lcd.fillRect(x, y, w, h, [,color]) +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +| **Description:** 　　 +| Fill the rectangle from the upper left point at **(x,y)** and **width** and **height** +| *Note:* 　　 +| *If fillcolor is not given, rectangle will be filled in current foreground color* + +| **Parament:** +| **w:** display phisical width in pixels (display's smaller dimension) +| **h:** display phisical height in pixels (display's larger dimension) +| **color:** optional, color values + +| **Example:** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.fillRect(180,30,122,10,lcd.BLUE) + +lcd.drawRoundRect(x, y, w, h, r [,color]) +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +| **Description:** 　　 +| Draw the rectangle with rounded corners from the upper left point at **(x,y)** and **width** and **height**. Corner radius is given by **r** argument +| *Note:* 　　 +| *If *color* is not given, current foreground color will be used* + +| **Parament:** +| **w:** display phisical width in pixels (display's smaller dimension) +| **h:** display phisical height in pixels (display's larger dimension) +| **r:** the radius of circle +| **color:** optional, color values + +| **Example:** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.drawRoundRect(180,50,122,10,4,lcd.BLUE)  + +lcd.fillRoundRect(x, y, w, h, r [,color]) +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +| **Description:** 　　 +| Fill the rectangle with rounded corners from the upper left point at **(x,y)** and **width** and **height**. Corner radius is given by **r** argument +| *Note:* 　　 +| If **color** is not given, current foreground color will be used + +| **Parament:** +| **w:** display phisical width in pixel (display's smaller dimension) +| **h:** display phisical height in pixels (display's larger dimension) +| **r:** the radius of circle +| **color:** optional, color values + +| **Example:** +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.fillRoundRect(180,70,122,10,4,lcd.BLUE)  + +lcd.print('text', [x, y]) +>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +| **Description:** 　　 +| Print the **text** at position **(x,y)** + +| **Parament:** +| **text:** the string need to print + +| **Example:** +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.print('this is a print text function', 80, 80) + +lcd.clear([color]) +>>>>>>>>>>>>>>>>>>>>>> + +| **Description:** 　　 +| Clear the screen with default background color orspecific color if given + +| **Parament:** +| **color:** optional, color values + +| **Example:** +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.clear() + +--------------------- + +Usage +------ + +.. code:: python + + from machine import SPI, Pin + from display import LCD + + spi = SPI(1, baudrate=32000000, mosi=Pin(23), miso=Pin(19), sck=Pin(18)) + + lcd = LCD(spi = spi) #lcd init + lcd.fillScreen(lcd.BLACK) #set the default background color + + lcd.drawLine(0, 0, lcd.WHITE) + lcd.drawTriangle(22, 22, 69, 98, 51, 22, lcd.RED) + lcd.fillTriangle(122, 122, 169, 198, 151, 182, lcd.RED) + lcd.drawCircle(180, 180, 10, lcd.BLUE) + lcd.fillcircle(100, 100, 10, lcd.BLUE) + lcd.drawRect(180, 12, 122, 10, lcd.BLUE) + lcd.fillRect(180, 30, 122, 10, lcd.BLUE) + lcd.drawRoundRect(180, 50, 122, 10, 4, lcd.BLUE) + lcd.fillRoundRect(180, 70, 122, 10, 4, lcd.BLUE) + lcd.print('this is a print text function', 80, 80) + diff --git a/en/api-reference/lcd/lcd.rst b/en/api-reference/lcd/lcd.rst new file mode 100644 index 00000000..913a225d --- /dev/null +++ b/en/api-reference/lcd/lcd.rst @@ -0,0 +1,231 @@ +Display Module +-------------- + +Methods +~~~~~~~ + +1.lcd.setRotation(2) +^^^^^^^^^^^^^^^^^^^^ + +***Description:*** ***Parament:*** ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.setRotation(2) + +2.lcd.setColor(foreground\_color[,background\_color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Set the default foreground/background color +***Parament:*** ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.setColor(lcd.RED) + lcd.setColor(lcd.ORANGE, LCD.DARKCYAN) + +3.lcd.setTextColor(foreground\_color[,background\_color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Set the default foreground/background color for +text ***Parament:*** \* ***color：*** color values are given as 24 bit +integer numbers, 8-bit per color ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.setTextColor(lcd.PINK) + lcd.setTextColor(lcd.ORANGE, LCD.DARKCYAN) + +4.lcd.fillScreen(color) +^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Fill the screen with the given color +***Parament:*** \* ***color：*** color values are given as 24 bit +integer numbers, 8-bit per color ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.fillScreen(lcd.color565(0x00, 0x00, 0x00)) + +5.lcd.drawPixel(x, y [,color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Draw the pixel at position **(x,y)** *Note:* +　　If color is not given, current foreground color is used +***Parament:*** \* ***color：*** color values are given as 24 bit +integer numbers, 8-bit per color ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.drawPixel(22,22,lcd.RED)   + +6.lcd.drawLine(x, y, x1, y1 [,color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Draw the line from point **(x,y)** to point +**(x1,y1)** *Note:* 　　If color is not given, current foreground color +is used ***Parament:*** \* ***color：*** color values are given as 24 +bit integer numbers, 8-bit per color ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.drawLine(0,0,lcd.WHITE)  + +7.lcd.drawTriangle(x, y, x1, y1, x2, y2 [,color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Draw the triangel between points **(x,y)**, +**(x1,y1)** and **(x2,y2)** *Note:* 　　If color is not given, current +foreground color is used 　 ***Parament:*** \* ***color：*** color +values are given as 24 bit integer numbers, 8-bit per color +***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.drawTriangle(22,22,69,98,51,22,lcd.RED) + +8.lcd.fillTriangle(x, y, x1, y1, x2, y2 [,color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Fill the triangel between points **(x,y)**, +**(x1,y1)** and **(x2,y2)** *Note:* 　　If **color** is not given, +triangle will be filled in current foreground color ***Parament:*** \* +***color：*** color values are given as 24 bit integer numbers, 8-bit +per color ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.fillTriangle(122,122,169,198,151,182,lcd.RED) + +　 #### 9.lcd.drawCircle(x, y, r [,color]) ***Description:*** 　　Draw +the circle with center at **(x,y)** and radius **r** *Note:* 　　If +**color** is not given, current foreground color is used + +***Parament:*** \* ***r:*** the radius of circle \* ***color：*** color +values are given as 24 bit integer numbers, 8-bit per color +***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.drawCircle(180,180,10,lcd.BLUE)  + +10.lcd.fillCircle(x, y, r [,color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Fill the circle with center at **(x,y)** and +radius **r** *Note:* 　　If **color** is not given, current foreground +color will be used + +***Parament:*** \* ***r:*** the radius of circle \* ***color：*** color +values are given as 24 bit integer numbers, 8-bit per color +***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.fillcircle(100,100,10,lcd.BLUE)  + +11.lcd.drawRect(x, y, width, height, [,color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Draw the rectangle from the upper left point at +**(x,y)** and width **width** and height **height** *Note:* 　　If +**color** is not given, rectangle will be drawn in current foreground +color ***Parament:*** \* ***width:*** optional, default=240, display +phisical width in pixels (display's smaller dimension). \* ***height:*** +optional, default=320, display phisical height in pixels (display's +larger dimension). \* ***color：*** color values are given as 24 bit +integer numbers, 8-bit per color ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.drawRect(180,12,122,10,lcd.BLUE) + +12.lcd.fillRect(x, y, width, height, [,color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Fill the rectangle from the upper left point at +**(x,y)** and width **width** and height **height** *Note:* 　　If +**fillcolor** is not given, rectangle will be filled in current +foreground color ***Parament:*** \* ***width:*** optional, default=240, +display phisical width in pixels (display's smaller dimension). \* +***height:*** optional, default=320, display phisical height in pixels +(display's larger dimension). \* ***color：*** color values are given as +24 bit integer numbers, 8-bit per color ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.fillRect(180,30,122,10,lcd.BLUE) + +13.lcd.drawRoundRect(x, y, width, height, r [,color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Draw the rectangle with rounded corners from the +upper left point at *(x,y)* and width **width** and height **height**. +Corner radius is given by **r** argument *Note:* 　　If *color* is not +given, current foreground color will be used ***Parament:*** \* +***width:*** optional, default=240, display phisical width in pixels +(display's smaller dimension) \* ***height:*** optional, default=320, +display phisical height in pixels (display's larger dimension). \* +***r:*** the radius of circle \* ***color：*** color values are given as +24 bit integer numbers, 8-bit per color ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.drawRoundRect(180,50,122,10,4,lcd.BLUE)  + +14.lcd.fillRoundRect(x, y, width, height, r [,color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Fill the rectangle with rounded corners from the +upper left point at *(x,y)* and width **width** and height **height**. +Corner radius is given by **r** argument *Note:* 　　If **color** is not +given, current foreground color will be used ***Parament:*** \* +***width:*** optional, default=240, display phisical width in pixels +(display's smaller dimension) \* ***height:*** optional, default=320, +display phisical height in pixels (display's larger dimension). \* +***r:*** the radius of circle \* ***color：*** color values are given as +24 bit integer numbers, 8-bit per color ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.fillRoundRect(180,70,122,10,4,lcd.BLUE)  + +15.lcd.print('text',x,y) +^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Print the **text** at position **(x,y)** +***Parament:*** + +***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.print('this is a print text function', 80, 80) + +16.lcd.clear([color]) +^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Clear the screen with default background color or +specific color if given ***Parament:*** \* ***color：*** color values +are given as 24 bit integer numbers, 8-bit per color ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.clear() + diff --git a/en/conf.py b/en/conf.py new file mode 100644 index 00000000..2d4c2573 --- /dev/null +++ b/en/conf.py @@ -0,0 +1,133 @@ +# -*- coding: utf-8 -*- +# +# English Languag`e 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 +# import sys, os +# sys.path.insert(0, os.path.abspath('..')) +# from conf_common import * + +# General information about the project. +project = u'M5Stack' +copyright = u'2017 - 2018, M5Stack Inc' +author = u'M5Stack' + +# The short X.Y version +version = u'' +# The full version, including alpha/beta/rc tags +release = u'1.0.1' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +language = 'en' + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +import sphinx_rtd_theme +html_theme = 'sphinx_rtd_theme' +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] +html_static_path = ['_static/M5Stack_MicroPython_UserGuidePictures'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'M5Stackdoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'M5Stack.tex', u'M5Stack Documentation', + u'M5Stack', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'm5stack', u'M5Stack Documentation', + [author], 1) +] + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'M5Stack', u'M5Stack Documentation', + author, 'M5Stack', 'One line description of project.', + 'Miscellaneous'), +] + +# -- AutoStructify Setting ---------------------------------------------- + +# At top on conf.py (with other import statements) +import recommonmark +from recommonmark.transform import AutoStructify + +# At the bottom of conf.py +def setup(app): + app.add_config_value('recommonmark_config', { + 'url_resolver': lambda url: github_doc_root + url, + 'auto_toc_tree_section': 'Contents', + }, True) + app.add_transform(AutoStructify) \ No newline at end of file diff --git a/en/get-started/M5Stack-Core-Arduino_Getting_Started_en.md b/en/get-started/M5Stack-Core-Arduino_Getting_Started_en.md new file mode 100644 index 00000000..a3a565c5 --- /dev/null +++ b/en/get-started/M5Stack-Core-Arduino_Getting_Started_en.md @@ -0,0 +1,111 @@ +# M5Stack-Core-Arduino —— Getting Started + +## **Windows** +#### 1. install `Arduino IDE` + +*download address* +https://www.arduino.cc/en/Main/Software + +![image](../../_static/screenshots/arduino_cc_package.png) + + +modified the path of Arduino as `D:\Program Files` as shown below + +![image](../../_static/screenshots/select_arduino_install_path.png) + + +Now my path of Arduino is `D:\Program Files\Arduino` + +![image](../../_static/screenshots/arduino_path.png) + + +#### 2. Download toolchain + +（Now my path of Arduino is `D:\Program Files\Arduino`） + +Enter the path `D:\Program Files\Arduino\hareware` via the terminal of Windows + +Execute the following commands on the terminal of Windows +> * new a directory named `espressif`, then enter this directory + +mkdir espressif && cd espressif + +![image](../../_static/screenshots/mkdir_espressif.png) + + +> * clone `esp32 idf` at the directory named `esp32` + +git clone --recursive https://github.com/espressif/arduino-esp32.git esp32 + +![image](../../_static/screenshots/download_idf.png) + + + +#### 3. ESP32 toolchain + +Enter the path `D:\Program Files\arduino\hardware\espressif\esp32\tools` +double click on `get.exe` + +![image](../../_static/screenshots/select_get_exe_file.png) + +![image](../../_static/screenshots/download_xtensa_tools.png) + + +#### 4. Download the M5Stack Lib via Arduino IDE + +Open Arduino IDE, then Select `Sketch`->`Include Library`->`Manage Libraries...` +Search `M5Stack` and install it + +![image](../../_static/screenshots/select_arduino_lib.png) + +![image](../../_static/screenshots/download_m5stack_lib.png) + + +## Example + +The USB cable connects to M5Stack Core, then select your serial port which is connected M5Stack Core. +Select a demo example, compile and upload + +#### 1. Open a example likes `FactoryTest.ino` + +![image](../../_static/screenshots/select_demo.png) + + + +Comfire your board name, baudrate, the specified serial port: M5Stack-Core-ESP32、921600、COM3 + +![image](../../_static/screenshots/select_board_and_com.png) + +After upload seccessfully, open the Serial Monitor + +![image](../../_static/screenshots/FactoryTest_result.png) + +#### 2. New a M5Stack program + +Open Arduino IDE, then new a `.ino` file, rename it as `my_test.ino` + +Copy the below code to my_test.ino + +```cpp +#include + +// the setup routine runs once when M5Stack starts up +void setup(){tack + + // Initialize the M5Stack object + M5.begin(); + + // LCD display + M5.Lcd.print("Hello World!"); + M5.Lcd.print("M5Stack is running successfully!"); +} + +// the loop routine runs over and over again forever +void loop() { + +} +``` + +compile it and upload, the M5Stack screen will show "Hello World!" "M5Stack is running successfully!" + + diff --git a/en/get-started/M5Stack-Core-Arduino_Getting_Started_zh_CN.md b/en/get-started/M5Stack-Core-Arduino_Getting_Started_zh_CN.md new file mode 100644 index 00000000..e439102b --- /dev/null +++ b/en/get-started/M5Stack-Core-Arduino_Getting_Started_zh_CN.md @@ -0,0 +1,132 @@ +# M5Stack-Core-Arduino —— Getting Started + + +## 一、安装 USB 驱动 + +点击以下链接，下载 M5Stack-Core 的 USB 转串口驱动 + +https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers + +下载完之后，解压，根据系统位数，双击对应可执行文件 + +(Windows 32位，执行 CP210xVCPInstaller_x68.exe；Windows 64位，执行 CP210xVCPInstaller_x64.exe；) + +*判断驱动安装是否成功：* +如果安装成功，在插入 M5Stack 主控之后，设备管理器如下图所示出现，Silicon Labs 的 CP21x 系列串口端口号 +(我的电脑当前串口号是 COM3) + +![image](screenshots/my_com.png) + + +## 二、开发环境 +## **Windows** +### 1、安装 Arduino IDE + +*下载地址* +https://www.arduino.cc/en/Main/Software + +![image](screenshots/arduino_cc_package.png) + + +如下图所示修改 Arduino 路径为 D:\Program Files + +![image](screenshots/select_arduino_install_path.png) + + +此时，Arduino 的安装路径为 D:\Program Files\Arduino + +![image](screenshots/arduino_path.png) + + +### 2、下载 ESP32 相关支持包 + +（我的 Arduino 当前路径是 D:\Program Files\arduino） + +进入 Arduino 安装路径的 hareware 文件夹，按住 Shift 键的同时，右键选择“在此处打开命令窗口” + + +在打开的 Windows 终端 CMD 中输入如下命令 + +> * 创建 espressif 目录，并切换到此目录下 + +mkdir espressif && cd espressif + +![image](screenshots/mkdir_espressif.png) + + +> * 将 esp32 idf clone 在文件夹 esp32 下 + +git clone --recursive https://github.com/espressif/arduino-esp32.git esp32 + +![image](screenshots/download_idf.png) + + + +### 3、下载 ESP32 编译链 tools + +进入此路径 D:\Program Files\arduino\hardware\espressif\esp32\tools +选中并双击执行 get.exe 文件 + +![image](screenshots/select_get_exe_file.png) + +![image](screenshots/download_xtensa_tools.png) + + +### 4、Arduino IDE 中下载 M5Stack 的库 + +打开 Arduino IDE 之后，选择“项目”->“加载库”->“管理库...”，搜索“M5Stack”并点击“安装” + +![image](screenshots/select_arduino_lib.png) + +![image](screenshots/download_m5stack_lib.png) + + +## 三、示例 + +USB 线连接 M5Stack 主控，选择串口和一个示例程序，compile and upload + +### 1、打开一个示例程序，如打开 FactoryTest.ino + +![image](screenshots/select_demo.png) + + + +确认连接板子名称、串口波特率和当前串口号分别：M5Stack-Core-ESP32、921600、COM3(当前电脑串口号) + +![image](screenshots/select_board_and_com.png) + + +编译运行成功之后，串口监视窗口显示如下 + + +![image](screenshots/FactoryTest_result.png) + +### 2、新建一个 M5Stack 程序 + +打开 Arduino IDE 之后，新建 .ino 文件，并保存为 my_test.ino + +将如下代码拷贝进文件中。 + +```cpp +#include + +// the setup routine runs once when M5Stack starts up +void setup(){tack + + // Initialize the M5Stack object + M5.begin(); + + // LCD display + M5.Lcd.print("Hello World!"); + M5.Lcd.print("M5Stack is running successfully!"); +} + +// the loop routine runs over and over again forever +void loop() { + +} +``` + +点击编译运行，此时 M5Stack 显示器显示 "Hello World!" "M5Stack is running successfully!" + + diff --git a/en/get-started/M5Stack-MicroPython_Getting_Started.md b/en/get-started/M5Stack-MicroPython_Getting_Started.md new file mode 100644 index 00000000..d27f9da3 --- /dev/null +++ b/en/get-started/M5Stack-MicroPython_Getting_Started.md @@ -0,0 +1,118 @@ + +### CONTENT + +1. [Burn Firmware](#Burn-Firmwared) + + - [1. Download Firmware](#1-download-firmware) + + - [2. Burn to M5Stack](#2-Burn-to-M5Stack) + +1. [Connect Wi-Fi](#connect-wi-fi) + +3. [Binding device](#binding-device) + +4. [Coding MicroPython](#coding-micropython) + + +### Burn Firmware +#### 1. Download Firmware +https://github.com/m5stack/M5Cloud/tree/master/firmwares + +Now, the M5Cloud firmware I downloaded named `m5cloud-20180516-v0.4.0.bin` +and it saved at `~/smbshare` + +#### 2. Burn to M5Stack +![image](../../_static/windows-logo.png) | ![image](../../_static/linux-logo.png) | ![image](../../_static/macos-logo.png) +---|---|--- +Windows | Linux | MacOS + +***Windows*** + +open Flash Download Tools([点击下载](https://www.espressif.com/sites/default/files/tools/flash_download_tools_v3.6.4.rar)) apply by Espressif, choose `ESP32 DownloadTool` option and execute three steps ( *choose firmware file, your serial port, erase and program flash* ) as shown below + +![image](../../_static/M5Stack_MicroPython_UserGuidePictures/windows_download_firmware.png) + + + +***MacOS/Linux*** + +*1. Check port on Linux and MacOS* + + To check the device name for the serial port of your M5Stack board (or external converter dongle), run this command two times, first with the board / dongle unplugged, then with plugged in. The port which appears the second time is the one you need: + + Linux + + ``` + ls /dev/tty* + ``` + + MacOS + + ``` + ls /dev/cu.* + ``` + + +*2. Adding user to `dialout` on Linux* + +The currently logged user should have read and write access the serial port over USB. On most Linux distributions, this is done by adding the user to `dialout` group with the following command: + + ``` + sudo usermod -a -G dialout $USER + ``` +Now, my serial port named `ttyUSB0` + +*3. Download M5Cloud firmware to M5Stack board* + - Installing esptool： + ``` + pip install esptool + ``` + - Erase flash on M5Stack: + ``` + esptool.py --chip esp32 --port /dev/ttyUSB0 erase_flash + ``` + - Download firmware to M5Stack: + ``` + esptool.py --chip esp32 --port /dev/ttyUSB0 write_flash --flash_mode dio -z 0x1000 m5cloud-20180516-v0.4.0.bin + ``` + +### Connect Wi-Fi + + +Mobile Phone or PC connect to M5Stack AP(like `M5Stack-a67c`), and then open brower to login 192.168.4.1 setting your LAN SSID and Password + +![image](../../_static/M5Stack_MicroPython_UserGuidePictures/m5stack_connet_wifi.png) + +### Binding device + +*1.login http://io.m5stack.com and register your own account(or login your account)* + +*2. press `Device->Add` buttom on M5Cloud IDE for binding M5Stack board to your account* + +*3. Input the Check Code for the M5Stack screen display，Check Code is random, after 60s will refresh* + +![image](../../_static/M5Stack_MicroPython_UserGuidePictures/WebIDE_check_code.png) + +### Coding MicroPython + +*1. create a new python project* + +![image](../../_static/M5Stack_MicroPython_UserGuidePictures/create_a_new_project.png) + +*2. write your own code and press `Upload & Run` buttom on the M5Cloud IDE* + +copy below code to `main.py` file and press `Upload & Run` + +``` python +from m5stack import lcd + +lcd.clear() +lcd.setCursor(0, 0) +lcd.setColor(lcd.WHITE) + +lcd.print("Hello World!") + +``` + +![image](../../_static/M5Stack_MicroPython_UserGuidePictures/display_hello_world.png) + diff --git a/en/get-started/add-idf_path-to-profile.rst b/en/get-started/add-idf_path-to-profile.rst new file mode 100644 index 00000000..52b30bb1 --- /dev/null +++ b/en/get-started/add-idf_path-to-profile.rst @@ -0,0 +1,65 @@ +Add IDF_PATH to User Profile +============================ +`zh_CN:[中文]` + +To preserve setting of ``IDF_PATH`` environment variable between system restarts, add it to the user profile, following instructions below. + + +.. _add-idf_path-to-profile-windows: + +Windows +------- + +The user profile scripts are contained in ``C:/msys32/etc/profile.d/`` directory. They are executed every time you open an MSYS2 window. + +#. Create a new script file in ``C:/msys32/etc/profile.d/`` directory. Name it ``export_idf_path.sh``. + +#. Identify the path to ESP-IDF directory. It is specific to your system configuration and may look something like ``C:\msys32\home\user-name\esp\esp-idf`` + +#. Add the ``export`` command to the script file, e.g.:: + + export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf" + + Remember to replace back-slashes with forward-slashes in the original Windows path. + +#. Save the script file. + +#. Close MSYS2 window and open it again. Check if ``IDF_PATH`` is set, by typing:: + + printenv IDF_PATH + + The path previusly entered in the script file should be printed out. + +If you do not like to have ``IDF_PATH`` set up permanently in user profile, you should enter it manually on opening of an MSYS2 window:: + + export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf" + +If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`. + + +.. _add-idf_path-to-profile-linux-macos: + +Linux and MacOS +--------------- + +Set up ``IDF_PATH`` by adding the following line to ``~/.profile`` file:: + + export IDF_PATH=~/esp/esp-idf + +Log off and log in back to make this change effective. + +.. note:: + + If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead. + +Run the following command to check if ``IDF_PATH`` is set:: + + printenv IDF_PATH + +The path previously entered in ``~/.profile`` file (or set manually) should be printed out. + +If you do not like to have ``IDF_PATH`` set up permanently, you should enter it manually in terminal window on each restart or logout:: + + export IDF_PATH=~/esp/esp-idf + +If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`. diff --git a/en/get-started/establish-serial-connection.rst b/en/get-started/establish-serial-connection.rst new file mode 100644 index 00000000..2192fd0b --- /dev/null +++ b/en/get-started/establish-serial-connection.rst @@ -0,0 +1,132 @@ +Establish Serial Connection with ESP32 +====================================== + +This section provides guidance how to establish serial connection between ESP32 and PC. + + +Connect ESP32 to PC +-------------------- + +Connect the ESP32 board to the PC using the USB cable. If device driver does not install automatically, identify USB to serial converter chip on your ESP32 board (or external converter dongle), search for drivers in internet and install them. + +Below are the links to drivers for ESP32 boards produced by Espressif: + +* ESP32-PICO-KIT and ESP32-DevKitC - `CP210x USB to UART Bridge VCP Drivers `_ + +* ESP32-WROVER-KIT and ESP32 Demo Board - `FTDI Virtual COM Port Drivers `_ + +Above drivers are primarily for reference. They should already be bundled with the operating system and installed automatically once one of listed boards is connected to the PC. + + +Check port on Windows +--------------------- + +Check the list of identified COM ports in the Windows Device Manager. Disconnect ESP32 and connect it back, to verify which port disappears from the list and then shows back again. + +Figures below show serial port for ESP32 DevKitC and ESP32 WROVER KIT + +.. figure:: ../../_static/esp32-devkitc-in-device-manager.png + :align: center + :alt: USB to UART bridge of ESP32-DevKitC in Windows Device Manager + :figclass: align-center + + USB to UART bridge of ESP32-DevKitC in Windows Device Manager + +.. figure:: ../../_static/esp32-wrover-kit-in-device-manager.png + :align: center + :alt: Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager + :figclass: align-center + + Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager + + +Check port on Linux and MacOS +----------------------------- + +To check the device name for the serial port of your ESP32 board (or external converter dongle), run this command two times, first with the board / dongle unplugged, then with plugged in. The port which appears the second time is the one you need: + +Linux :: + + ls /dev/tty* + +MacOS :: + + ls /dev/cu.* + + +.. _linux-dialout-group: + +Adding user to ``dialout`` on Linux +----------------------------------- + +The currently logged user should have read and write access the serial port over USB. On most Linux distributions, this is done by adding the user to ``dialout`` group with the following command:: + + sudo usermod -a -G dialout $USER + +Make sure you re-login to enable read and write permissions for the serial port. + + +Verify serial connection +------------------------ + +Now verify that the serial connection is operational. You can do this using a serial terminal program. In this example we will use `PuTTY SSH Client `_ that is available for both Windows and Linux. You can use other serial program and set communication parameters like below. + +Run terminal, set identified serial port, baud rate = 115200, data bits = 8, stop bits = 1, and parity = N. Below are example screen shots of setting the port and such transmission parameters (in short described as 115200-8-1-N) on Windows and Linux. Remember to select exactly the same serial port you have identified in steps above. + +.. figure:: ../../_static/putty-settings-windows.png + :align: center + :alt: Setting Serial Communication in PuTTY on Windows + :figclass: align-center + + Setting Serial Communication in PuTTY on Windows + +.. figure:: ../../_static/putty-settings-linux.png + :align: center + :alt: Setting Serial Communication in PuTTY on Linux + :figclass: align-center + + Setting Serial Communication in PuTTY on Linux + + +Then open serial port in terminal and check, if you see any log printed out by ESP32. The log contents will depend on application loaded to ESP32. An example log by ESP32 is shown below. + +.. highlight:: none + +:: + + ets Jun 8 2016 00:22:57 + + rst:0x5 (DEEPSLEEP_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) + ets Jun 8 2016 00:22:57 + + rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) + configsip: 0, SPIWP:0x00 + clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00 + mode:DIO, clock div:2 + load:0x3fff0008,len:8 + load:0x3fff0010,len:3464 + load:0x40078000,len:7828 + load:0x40080000,len:252 + entry 0x40080034 + I (44) boot: ESP-IDF v2.0-rc1-401-gf9fba35 2nd stage bootloader + I (45) boot: compile time 18:48:10 + + ... + +If you see some legible log, it means serial connection is working and you are ready to proceed with installation and finally upload of application to ESP32. + +.. note:: + + For some serial port wiring configurations, the serial RTS & DTR pins need to be disabled in the terminal program before the ESP32 will boot and produce serial output. This depends on the hardware itself, most development boards (including all Espressif boards) *do not* have this issue. The issue is present if RTS & DTR are wired directly to the EN & GPIO0 pins. See the `esptool documentation`_ for more details. + +.. note:: + + Close serial terminal after verification that communication is working. In next step we are going to use another application to upload ESP32. This application will not be able to access serial port while it is open in terminal. + +If you got here from section :ref:`get-started-connect` when installing s/w for ESP32 development, then go back to section :ref:`get-started-configure`. + + +.. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader + + + diff --git a/en/get-started/get-started-ESP32CAM.md b/en/get-started/get-started-ESP32CAM.md new file mode 100644 index 00000000..42fa6632 --- /dev/null +++ b/en/get-started/get-started-ESP32CAM.md @@ -0,0 +1,25 @@ +# ESP32CAM User Guide + +## 1. Out-of-the-box Demo + +It is really really out of the box. Your ESP32CAM will immediately run without any code after you power it. + +1. plug usb cable into ESP32CAM and open the serial terminal on your computer. + +![image](screenshots/ESP32CAM_Terminal.png) + + +2. Then waitting a few seconds, you connect to a AP named "`M5CAM`" with your computer(or mobile phone). + +![image](screenshots/ESP32CAM_M5CAM.png) + + +3. And you open the browser on the computer(or mobile phone), enter a URL `http://192.168.4.1`. At the moment, your can see the real-time transmission of video by ESP32CAM on the browser. + +![image](screenshots/ESP32CAM_Browser.png) + +Now, A WebCam you achieved successfully ! + +*Note:* + +ESP32CAM AP only can connect with one device at a time. diff --git a/en/get-started/get-started-ESP32CAM.rst b/en/get-started/get-started-ESP32CAM.rst new file mode 100644 index 00000000..0b67f5fa --- /dev/null +++ b/en/get-started/get-started-ESP32CAM.rst @@ -0,0 +1,30 @@ +ESP32CAM User Guide +=================== + +1. Out-of-the-box Demo +---------------------- + +It is really really out of the box. Your ESP32CAM will immediately run +without any code after you power it. + +1. plug usb cable into ESP32CAM and open the serial terminal on your + computer. + +.. image:: ../../_static/screenshots/ESP32CAM_Terminal.png + +2. Then waitting a few seconds, you connect to a AP named "``M5CAM``\ " + with your computer(or mobile phone). + +.. image:: ../../_static/screenshots/ESP32CAM_M5CAM.png + +3. And you open the browser on the computer(or mobile phone), enter a + URL ``http://192.168.4.1``. At the moment, your can see the real-time + transmission of video by ESP32CAM on the browser. + +.. image:: ../../_static/screenshots/ESP32CAM_Browser.png + +Now, A WebCam you achieved successfully ! + +*Note:* + +ESP32CAM AP only can connect with one device at a time. diff --git a/en/get-started/get-started-M5Bala.md b/en/get-started/get-started-M5Bala.md new file mode 100644 index 00000000..38696aca --- /dev/null +++ b/en/get-started/get-started-M5Bala.md @@ -0,0 +1,30 @@ +# M5Bala +M5Stack balance car + +### Quick Start + +```bash +git clone https://github.com/m5stack/M5Bala.git +cd M5Bala +pio run +``` + +### Installing and compiling the software + +This project used Arduino framework develop, you must install the necessary tools and prepare the IDE environment. +- Download (and unzip) this repository +- Download and Install Visual Studio Code https://code.visualstudio.com/ +- Install the [PlatformIO Extension](https://platformio.org/get-started/ide?install=vscode) +- Install M5Stack [USB Driver](https://github.com/m5stack/M5Stack#installing-the-usb-driver) +- Install ESP32 Platform on PlatformIO +- Open the M5Bala Project folder on PlatformIO +- Build your project with *ctrl+alt+b* hotkey or using **Build** button on the PlatformIO Toolbar +![image](./docs/img/platformio-ide-vscode-build-project.png) + +### Dependent library +- M5Stack - [https://github.com/m5stack/M5Stack](https://github.com/m5stack/M5Stack) +- MPU6050_tockn - [https://github.com/tockn/MPU6050_tockn](https://github.com/tockn/MPU6050_tockn) +- NeoPixelBus - [https://github.com/Makuna/NeoPixelBus](https://github.com/Makuna/NeoPixelBus) + +### MicroPython +- [Examples](./mpy) diff --git a/en/get-started/get-started-M5Bala.rst b/en/get-started/get-started-M5Bala.rst new file mode 100644 index 00000000..db893625 --- /dev/null +++ b/en/get-started/get-started-M5Bala.rst @@ -0,0 +1,41 @@ +M5Bala +====== + +M5Stack balance car + +Quick Start +~~~~~~~~~~~ + +.. code:: bash + + git clone https://github.com/m5stack/M5Bala.git + cd M5Bala + pio run + +Installing and compiling the software +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This project used Arduino framework develop, you must install the +necessary tools and prepare the IDE environment. - Download (and unzip) +this repository - Download and Install Visual Studio Code +https://code.visualstudio.com/ - Install the `PlatformIO +Extension `__ - +Install M5Stack `USB +Driver `__ +- Install ESP32 Platform on PlatformIO - Open the M5Bala Project folder +on PlatformIO - Build your project with *ctrl+alt+b* hotkey or using +**Build** button on the PlatformIO Toolbar |image| + +Dependent library +~~~~~~~~~~~~~~~~~ + +- M5Stack - https://github.com/m5stack/M5Stack +- MPU6050\_tockn - https://github.com/tockn/MPU6050_tockn +- NeoPixelBus - https://github.com/Makuna/NeoPixelBus + +MicroPython +~~~~~~~~~~~ + +- `Examples <./mpy>`__ + +.. |image| image:: ./docs/img/platformio-ide-vscode-build-project.png diff --git a/docs/.nojekyll b/en/get-started/get-started-M5StackCore-Arduino.md similarity index 100% rename from docs/.nojekyll rename to en/get-started/get-started-M5StackCore-Arduino.md diff --git a/en/get-started/get-started-M5StackCore-Arduino.rst b/en/get-started/get-started-M5StackCore-Arduino.rst new file mode 100644 index 00000000..ef7e31c9 --- /dev/null +++ b/en/get-started/get-started-M5StackCore-Arduino.rst @@ -0,0 +1,116 @@ +M5Stack-Core-Arduino —— Getting Started +======================================= + +**Windows** +----------- + +1. install ``Arduino IDE`` +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*download address* https://www.arduino.cc/en/Main/Software + +.. image:: ../../_static/screenshots/arduino_cc_package.png + +modified the path of Arduino as ``D:\Program Files`` as shown below + +.. image:: ../../_static/screenshots/select_arduino_install_path.png + +Now my path of Arduino is ``D:\Program Files\Arduino`` + +.. image:: ../../_static/screenshots/arduino_path.png + +2. Download toolchain +^^^^^^^^^^^^^^^^^^^^^ + +（Now my path of Arduino is ``D:\Program Files\Arduino``\ ） + +Enter the path ``D:\Program Files\Arduino\hareware`` via the terminal of +Windows + +Execute the following commands on the terminal of Windows > \* new a +directory named ``espressif``, then enter this directory + +mkdir espressif && cd espressif + +.. image:: ../../_static/screenshots/mkdir_espressif.png + + + - clone ``esp32 idf`` at the directory named ``esp32`` + +git clone --recursive https://github.com/espressif/arduino-esp32.git +esp32 + +.. image:: ../../_static/screenshots/download_idf.png + +3. ESP32 toolchain +^^^^^^^^^^^^^^^^^^ + +Enter the path +``D:\Program Files\arduino\hardware\espressif\esp32\tools`` double click +on ``get.exe`` + +.. image:: ../../_static/screenshots/select_get_exe_file.png + +.. image:: ../../_static/screenshots/download_xtensa_tools.png + +4. Download the M5Stack Lib via Arduino IDE +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Open Arduino IDE, then Select +``Sketch`` -> ``Include Library`` -> ``Manage Libraries...`` Search +``M5Stack`` and install it + +.. image:: ../../_static/screenshots/select_arduino_lib.png + +.. image:: ../../_static/screenshots/download_m5stack_lib.png + +Example +------- + +The USB cable connects to M5Stack Core, then select your serial port +which is connected M5Stack Core. Select a demo example, compile and +upload + +1. Open a example likes ``FactoryTest.ino`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. image:: ../../_static/screenshots/select_demo.png + +Comfire your board name, baudrate, the specified serial port: +M5Stack-Core-ESP32、921600、COM3 + +.. image:: ../../_static/screenshots/select_board_and_com.png + +After upload seccessfully, open the Serial Monitor + +.. image:: ../../_static/screenshots/FactoryTest_result.png + +2. New a M5Stack program +^^^^^^^^^^^^^^^^^^^^^^^^ + +Open Arduino IDE, then new a ``.ino`` file, rename it as ``my_test.ino`` + +Copy the below code to my\_test.ino + +.. code:: cpp + + #include + + // the setup routine runs once when M5Stack starts up + void setup(){tack + + // Initialize the M5Stack object + M5.begin(); + + // LCD display + M5.Lcd.print("Hello World!"); + M5.Lcd.print("M5Stack is running successfully!"); + } + + // the loop routine runs over and over again forever + void loop() { + + } + +compile it and upload, the M5Stack screen will show "Hello World!" +"M5Stack is running successfully!" diff --git a/en/get-started/get-started-M5StackCore-Micropython.rst b/en/get-started/get-started-M5StackCore-Micropython.rst new file mode 100644 index 00000000..effb40ce --- /dev/null +++ b/en/get-started/get-started-M5StackCore-Micropython.rst @@ -0,0 +1,110 @@ +M5Stack-Core-MicroPython —— Getting Started +============================================ + +Burn Firmware +------------- + +1. Download Firmware +^^^^^^^^^^^^^^^^^^^^ + +https://github.com/m5stack/M5Cloud/tree/master/firmwares + +Now, the M5Cloud firmware I downloaded named +``m5cloud-20180516-v0.4.0.bin`` and it saved at ``~/smbshare`` + +2. Burn to M5Stack +^^^^^^^^^^^^^^^^^^ + ++--------------+--------------+--------------+ +| |windows| | |linux| | |macos| | ++--------------+--------------+--------------+ +| Windows | Linux | Mac OS | ++--------------+--------------+--------------+ + +.. |windows| image:: ../../_static/windows-logo.png + +.. |Linux| image:: ../../_static/linux-logo.png + +.. |MacOS| image:: ../../_static/macos-logo.png + + +**Windows** + +open Flash Download +Tools(\ `点击下载 `__) +apply by Espressif, choose ``ESP32 DownloadTool`` option and execute +three steps ( *choose firmware file, your serial port, erase and program +flash* ) as shown below + +.. image:: ../../_static/M5Stack_MicroPython_UserGuidePictures/windows_download_firmware.png + +**MacOS/Linux** + +*Comfire which serial port connected with* +TODO: linked to `Establish **serial** connection` + +*Download M5Cloud firmware to M5Stack board* - Installing esptool： +``pip install esptool`` - Erase flash on M5Stack: +``esptool.py --chip esp32 --port /dev/ttyUSB0 erase_flash`` - Download +firmware to M5Stack +``esptool.py --chip esp32 --port /dev/ttyUSB0 write_flash --flash_mode dio -z 0x1000 m5cloud-20180516-v0.4.0.bin`` + +Connect Wi-Fi +------------- + +Mobile Phone or PC connect to M5Stack AP(like ``M5Stack-a67c``), and +then open brower to login 192.168.4.1 setting your LAN SSID and Password + +.. figure:: ../../_static/M5Stack_MicroPython_UserGuidePictures/m5stack_connet_wifi.png + :align: center + :alt: m5stack_connet_wifi + :figclass: align-center + + m5stack_connet_wifi + +Binding device +--------------- + +*1.login http://io.m5stack.com and register your own account(or login +your account)* + +*2. press ``Device->Add`` buttom on M5Cloud IDE for binding M5Stack +board to your account* + +*3. Input the Check Code for the M5Stack screen display，Check Code is +random, after 60s will refresh* + +.. figure:: ../../_static/M5Stack_MicroPython_UserGuidePictures/WebIDE_check_code.png + :align: center + :alt: image + +Coding MicroPython +------------------- + +*1. create a new python project* + +.. figure:: ../../_static/M5Stack_MicroPython_UserGuidePictures/create_a_new_project.png + :align: center + :alt: image + +*2. write your own code and press ``Upload & Run`` buttom on the M5Cloud +IDE* + +copy below code to ``main.py`` file and press ``Upload & Run`` + +.. code:: python + + from m5stack import lcd + + lcd.clear() + lcd.setCursor(0, 0) + lcd.setColor(lcd.WHITE) + + lcd.print("Hello World!") + +.. figure:: ../../_static/M5Stack_MicroPython_UserGuidePictures/display_hello_world.png + :align: center + :alt: image + + + diff --git a/en/get-started/get-started-StepMotor.md b/en/get-started/get-started-StepMotor.md new file mode 100644 index 00000000..6afbc308 --- /dev/null +++ b/en/get-started/get-started-StepMotor.md @@ -0,0 +1,39 @@ +# M5Stack StepMotor Module + +Now, we consident that you can program M5Stack Core with M5Cloud. If not, please read the article [Getting Started with MicroPython](www.baidu.com) + +### Quick Start + +##### 1. M5Stack Core connect with StepMotor Module, then click `Upload Local File` for adding two necessary files `motor.py`, `i2c_bus.py` as shown below + +![image](../../_static/stepmotor_pic/show_motors_files_added.png) + +![image](../../_static/stepmotor_pic/upload_module_files.png) + +##### 2. Copy the below code to `main.py`, upload all file and `run` + +```python + +from m5stack import lcd +import motor +import utime + +lcd.clear() +lcd.setCursor(0, 0) +lcd.setColor(lcd.WHITE) +lcd.print("StepMotor Test: ") + +stepmotor_0 = motor.StepMotor(0x70) + +stepmotor_0.StepMotor_XYZ(0, 0, 0, 500) +utime.sleep(3) +stepmotor_0.StepMotor_XYZ(10.5, 10.5, 10.5, 500) +utime.sleep(3) +stepmotor_0.StepMotor_XYZ(0, 0, 0, 500) + +``` + +*Note: When step motor is running, supply it with 12V power.* + + + diff --git a/en/get-started/get-started-StepMotor.rst b/en/get-started/get-started-StepMotor.rst new file mode 100644 index 00000000..15b2a9a1 --- /dev/null +++ b/en/get-started/get-started-StepMotor.rst @@ -0,0 +1,46 @@ +M5Stack StepMotor Module +======================== + +Now, we consident that you can program M5Stack Core with M5Cloud. If +not, please read the article `Getting Started with +MicroPython`_ + +.. _Getting Started with MicroPython: get-started-M5StackCore-Micropython.html + +Quick Start +~~~~~~~~~~~ + +1. M5Stack Core connect with StepMotor Module +'''''''''''''''''''''''''''''''''''''''''''''' + +Click ``Upload Local File`` for adding two necessary files ``motor.py``, ``i2c_bus.py`` as shown below + +.. image:: ../../_static/stepmotor_pic/upload_module_files.png + +.. image:: ../../_static/stepmotor_pic/show_motors_files_added.png + + +2. Copy the below code to ``main.py``, upload all file and ``run`` +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +.. code:: python + + + from m5stack import lcd + import motor + import utime + + lcd.clear() + lcd.setCursor(0, 0) + lcd.setColor(lcd.WHITE) + lcd.print("StepMotor Test: ") + + stepmotor_0 = motor.StepMotor(0x70) + + stepmotor_0.StepMotor_XYZ(0, 0, 0, 500) + utime.sleep(3) + stepmotor_0.StepMotor_XYZ(10.5, 10.5, 10.5, 500) + utime.sleep(3) + stepmotor_0.StepMotor_XYZ(0, 0, 0, 500) + +*Note: When step motor is running, supply it with 12V power.* diff --git a/en/get-started/idf-monitor.rst b/en/get-started/idf-monitor.rst new file mode 100644 index 00000000..59abc654 --- /dev/null +++ b/en/get-started/idf-monitor.rst @@ -0,0 +1,218 @@ +*********** +IDF Monitor +*********** +`zh_CN:[中文]` + +The IDF Monitor tool is a Python program which runs when the ``make monitor`` target is invoked in IDF. + +It is mainly a serial terminal program which relays serial data to and from the target device's serial port, but it has some other IDF-specific features. + +Interacting With IDF Monitor +============================ + +- ``Ctrl-]`` will exit the monitor. +- ``Ctrl-T Ctrl-H`` will display a help menu with all other keyboard shortcuts. +- Any other key apart from ``Ctrl-]`` and ``Ctrl-T`` is sent through the serial port. + +Automatically Decoding Addresses +================================ + +Any time esp-idf prints a hexadecimal code address of the form ``0x4_______``, IDF Monitor will use addr2line_ to look up the source code location and function name. + +.. highlight:: none + +When an esp-idf app crashes and panics a register dump and backtrace such as this is produced:: + + Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was unhandled. + Register dump: + PC : 0x400f360d PS : 0x00060330 A0 : 0x800dbf56 A1 : 0x3ffb7e00 + A2 : 0x3ffb136c A3 : 0x00000005 A4 : 0x00000000 A5 : 0x00000000 + A6 : 0x00000000 A7 : 0x00000080 A8 : 0x00000000 A9 : 0x3ffb7dd0 + A10 : 0x00000003 A11 : 0x00060f23 A12 : 0x00060f20 A13 : 0x3ffba6d0 + A14 : 0x00000047 A15 : 0x0000000f SAR : 0x00000019 EXCCAUSE: 0x0000001d + EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0x00000000 + + Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90 + +IDF Monitor will augment the dump:: + + Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was unhandled. + Register dump: + PC : 0x400f360d PS : 0x00060330 A0 : 0x800dbf56 A1 : 0x3ffb7e00 + 0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:57 + (inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:52 + A2 : 0x3ffb136c A3 : 0x00000005 A4 : 0x00000000 A5 : 0x00000000 + A6 : 0x00000000 A7 : 0x00000080 A8 : 0x00000000 A9 : 0x3ffb7dd0 + A10 : 0x00000003 A11 : 0x00060f23 A12 : 0x00060f20 A13 : 0x3ffba6d0 + A14 : 0x00000047 A15 : 0x0000000f SAR : 0x00000019 EXCCAUSE: 0x0000001d + EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0x00000000 + + Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90 + 0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:57 + (inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:52 + 0x400dbf56: still_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:47 + 0x400dbf5e: dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:42 + 0x400dbf82: app_main at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:33 + 0x400d071d: main_task at /home/gus/esp/32/idf/components/esp32/./cpu_start.c:254 + +Behind the scenes, the command IDF Monitor runs to decode each address is:: + + xtensa-esp32-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS + + +Launch GDB for GDBStub +====================== + +By default, if an esp-idf app crashes then the panic handler prints registers and a stack dump as shown above, and then resets. + +Optionally, the panic handler can be configured to run a serial "gdb stub" which can communicate with a gdb_ debugger program and allow memory to be read, variables and stack frames examined, etc. This is not as versatile as JTAG debugging, but no special hardware is required. + +To enable the gdbstub, run ``make menuconfig`` and set :envvar:`CONFIG_ESP32_PANIC` option to ``Invoke GDBStub``. + +If this option is enabled and IDF Monitor sees the gdb stub has loaded, it will automatically pause serial monitoring and run GDB with the correct arguments. After GDB exits, the board will be reset via the RTS serial line (if this is connected.) + +Behind the scenes, the command IDF Monitor runs is:: + + xtensa-esp32-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf + + +Quick Compile and Flash +======================= + +The keyboard shortcut ``Ctrl-T Ctrl-F`` will pause IDF Monitor, run the ``make flash`` target, then resume IDF Monitor. Any changed source files will be recompiled before re-flashing. + +The keyboard shortcut ``Ctrl-T Ctrl-A`` will pause IDF Monitor, run the ``make app-flash`` target, then resume IDF Monitor. This is similar to ``make flash``, but only the main app is compiled and reflashed. + + +Quick Reset +=========== + +The keyboard shortcut ``Ctrl-T Ctrl-R`` will reset the target board via the RTS line (if it is connected.) + + +Pause the Application +===================== + +The keyboard shortcut ``Ctrl-T Ctrl-P`` will reset the target into bootloader, so that the board will run nothing. This is +useful when you want to wait for another device to startup. Then shortcut ``Ctrl-T Ctrl-R`` can be used to restart the +application. + + +Toggle Output Display +===================== + +Sometimes you may want to stop new output printed to screen, to see the log before. The keyboard shortcut ``Ctrl-T Ctrl-Y`` will +toggle the display (discard all serial data when the display is off) so that you can stop to see the log, and revert +again quickly without quitting the monitor. + +Filtering the Output +==================== + +The IDF monitor can be invoked as ``make monitor PRINT_FILTER=""`` with +specifying a custom ``PRINT_FILTER`` option for filtering outputs. The default +value is an empty string which means that everything will be printed. +Restrictions on what to print can be specified as a series of +``:`` items where ```` is the tag string and +```` is a character from set ``{N, E, W, I, D, V, *}`` referring to +a level for :doc:`logging <../../api-reference/system/log>`. For example, +``PRINT_FILTER="tag1:W"`` will match and print (only) the outputs written with +``ESP_LOGW("tag1", ...)`` or at lower verbosity level, i.e. ``ESP_LOGE("tag1", +...)``. Not specifying a +```` or using ``*`` defaults to Verbose level. + +.. note:: + The primary logging is set up at compilation time through the + :doc:`logging library<../../api-reference/system/log>`. + Output filtering by the IDF monitor is only a secondary solution because + one cannot filter something which has been disabled at compilation time. + The advantage of the secondary filtering is that one can use various + filtering options without recompiling the application. + +A restriction applies to tags when one wants to use them together with output +filtering: they cannot contain spaces, asterisks ``*`` and semicolons ``:``. + +If the last line of the output is written without an end of line then the +output filtering might get confused, i.e. the monitor starts to print the line and only +later finds out that the line should have not been written. This is a known +issue and can be avoided by always adding an end of line after printing +something (especially when no output follows immediately afterwards). + +Examples Of Filtering Rules: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Asterisk can be used to match any tags. However, specifying + ``PRINT_FILTER="*:I tag1:E"`` will print for ``tag1`` only errors because + the rule for ``tag1`` has a precedence over the rule for ``*``. +- The default (empty) rule is equivalent to ``*:V`` because matching every tag + at level Verbose or lower means matching everything. +- Rule ``"tag1:W tag1:E"`` is equivalent to ``"tag1:E"`` because any + consequent occurrence of the same tag name overwrites the previous one. +- Rule ``"tag1:I tag2:W"`` will print only ``tag1`` at verbosity level Info or + lower and ``tag2`` at verbosity level Warning or lower. +- Rule ``"tag1:I tag2:W tag3:N"`` is essentially equivalent to the previous + one because ``tag3:N`` specifies that ``tag3`` should not be printed. +- ``tag3:N`` in rule ``"tag1:I tag2:W tag3:N *:V"`` is more meaningful because + in this context the result will be that ``tag3`` will not be printed, + ``tag1`` and ``tag2`` will be at the specified (or lower) verbosity level + and everything else will be printed by default. +- ``"*:N"`` will suppress all outputs even prints made by something else than + the logging functions, e.g. ``printf``. For printing those outputs one need + to use ``*:E`` or higher verbosity level. +- Rules ``"tag1:V"``, ``"tag1:v"``, ``"tag1:"``, ``"tag1:*"`` and ``"tag1"`` + are all equivalent ones. + +A More Complex Filtering Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following log snippet was acquired using ``make monitor``:: + + load:0x40078000,len:13564 + entry 0x40078d4c + E (31) esp_image: image at 0x30000 has invalid magic byte + W (31) esp_image: image at 0x30000 has invalid SPI mode 255 + E (39) boot: Factory app partition is not bootable + I (568) cpu_start: Pro cpu up. + I (569) heap_init: Initializing. RAM available for dynamic allocation: + I (603) cpu_start: Pro cpu start user code + D (309) light_driver: [light_init, 74]:status: 1, mode: 2 + D (318) vfs: esp_vfs_register_fd_range is successful for range <54; 64) and VFS ID 1 + I (328) wifi: wifi driver task: 3ffdbf84, prio:23, stack:4096, core=0 + +The captured output for ``make monitor PRINT_FILTER="wifi esp_image:E light_driver:I"`` is the following:: + + E (31) esp_image: image at 0x30000 has invalid magic byte + I (328) wifi: wifi driver task: 3ffdbf84, prio:23, stack:4096, core=0 + +``make monitor PRINT_FILTER="light_driver:D esp_image:N boot:N cpu_start:N vfs:N wifi:N *:V"`` gives the following output:: + + load:0x40078000,len:13564 + entry 0x40078d4c + I (569) heap_init: Initializing. RAM available for dynamic allocation: + D (309) light_driver: [light_init, 74]:status: 1, mode: 2 + +Simple Monitor +============== + +Earlier versions of ESP-IDF used the pySerial_ command line program miniterm_ as a serial console program. + +This program can still be run, via ``make simple_monitor``. + +IDF Monitor is based on miniterm and shares the same basic keyboard shortcuts. + + +Known Issues with IDF Monitor +============================= + +Issues Observed on Windows +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- If you are using the supported Windows environment and receive the error "winpty: command not found" then run ``pacman -S winpty`` to fix. +- Arrow keys and some other special keys in gdb don't work, due to Windows Console limitations. +- Occasionally when "make" exits, it may stall for up to 30 seconds before idf_monitor resumes. +- Occasionally when "gdb" is run, it may stall for a short time before it begins communicating with the gdbstub. + + +.. _addr2line: https://sourceware.org/binutils/docs/binutils/addr2line.html +.. _gdb: https://sourceware.org/gdb/download/onlinedocs/ +.. _pySerial: https://github.com/pyserial/pyserial +.. _miniterm: https://pyserial.readthedocs.org/en/latest/tools.html#module-serial.tools.miniterm diff --git a/en/get-started/index.md b/en/get-started/index.md new file mode 100644 index 00000000..a9086aa3 --- /dev/null +++ b/en/get-started/index.md @@ -0,0 +1,39 @@ +## Get Started + +This document is intended to help users set up the software environment(`Arudino`, `MicroPython`) for development of M5Stack. Through a simple example we would like to illustrate how to develop M5Stack boards, firmware(`Arduino`) or source files(`MicroPython`) download to M5Stack boards. + + +### Introduction + +TODO: add introduction of hardware source on M5Stack Core + + +### What You Need + +To develop applications for M5Stack Core you need: + +* **PC** loaded with either Windows, Linux or Mac operating system +* a **M5Stack Core** with Type-C cable + +Before setting development environment, the three steps you need to follow: + +1. Establish **serial** connection +TODO: linked to `Establish **serial** connection` +2. Getting of **ESP-IDF** from GitHub + +### Your Boards/Modules + +If you have one of M5Stack development boards/modules listed below, click on provided links to get you up and running. + +![image](../../_static/windows-logo.png) | ![image](../../_static/linux-logo.png) | ![image](../../_static/macos-logo.png) +---|---|--- +M5StackCore | M5GO | ESP32CAM + +Develop M5Stack Core with Arduino IDE +Develop M5Stack Core with Micropython +Develop ESP32CAM with Micropython + + +### Some Questions + +TODO: add-idf_path-to-profile linked to FAQ diff --git a/en/get-started/index.rst b/en/get-started/index.rst new file mode 100644 index 00000000..e4cb6e93 --- /dev/null +++ b/en/get-started/index.rst @@ -0,0 +1,78 @@ +*********** +Get Started +*********** + +This document is intended to help users set up the software environment for development of applications. Through a simple example we would like to illustrate how to develop M5Stack boards, firmware(`Arduino IDE`) or source files(`Micropython`) download to M5Stack boards. + + +Introduction +============ + + +What You Need +============= + +To develop applications for M5Stack Core you need: + +* **PC** loaded with either Windows, Linux or Mac operating system +* a **M5Stack Core** with Type-C cable + + +Your boards +============ + +If you have one of ESP32 development boards listed below, click the corresponding one to start your development. + +============================ ============================ ============================ +|Core with Arduino|_ |Core with Micropython|_ |M5GO|_ +---------------------------- ---------------------------- ---------------------------- +`Core with Arduino`_ `Core with Micropython`_ `M5GO`_ +---------------------------- ---------------------------- ---------------------------- +|ESP32CAM|_ |M5Stack STEPMOTOR Module|_ |M5Bala|_ +---------------------------- ---------------------------- ---------------------------- +`ESP32CAM`_ `M5Stack STEPMOTOR Module`_ `M5Bala`_ +============================ ============================ ============================ + + +.. |Core with Arduino| image:: ../../_static/pics/m5-arduino.jpg +.. _Core with Arduino: get-started-M5StackCore-Arduino.html + +.. |Core with Micropython| image:: ../../_static/pics/m5-micropython.jpg +.. _Core with Micropython: get-started-M5StackCore-Micropython.html + +.. |M5GO| image:: ../../_static/pics/M5GO.jpg +.. _M5GO: get-started-M5StackCore-Micropython.html + +.. |ESP32CAM| image:: ../../_static/pics/ESP32CAM.jpg +.. _ESP32CAM: get-started-ESP32CAM.html + +.. |M5Stack STEPMOTOR Module| image:: ../../_static/pics/m5-stepmotor.jpg +.. _M5Stack STEPMOTOR Module: get-started-StepMotor.html + +.. |M5Bala| image:: ../../_static/pics/M5Bala.jpg +.. _M5Bala: get-started-M5Bala.html + + +.. toctree:: + :maxdepth: 1 + :hidden: + + M5Stack Core with Arduino IDE + M5Stack Core with Micropython + M5GO + ESP32CAM + M5Stack STEPMOTOR Module + M5Bala + + + + +Related Documents +================= + +.. toctree:: + :maxdepth: 1 + + add-idf_path-to-profile + establish-serial-connection + diff --git a/en/get-started/make-project.rst b/en/get-started/make-project.rst new file mode 100644 index 00000000..c7cba3bc --- /dev/null +++ b/en/get-started/make-project.rst @@ -0,0 +1,74 @@ +Build and Flash with Make +========================= +`zh_CN:[中文]` + + +Finding a project +----------------- + +As well as the `esp-idf-template `_ project, ESP-IDF comes with some example projects on github in the `examples` directory. + +Once you've found the project you want to work with, change to its directory and you can configure and build it. + + +Configuring your project +------------------------ + +:: + + make menuconfig + + +Compiling your project +---------------------- + +:: + + make all + +... will compile app, bootloader and generate a partition table based on the config. + + +Flashing your project +--------------------- + +When ``make all`` finishes, it will print a command line to use esptool.py to flash the chip. However you can also do this from make by running:: + + make flash + +This will flash the entire project (app, bootloader and partition table) to a new chip. The settings for serial port flashing can be configured with `make menuconfig`. + +You don't need to run ``make all`` before running ``make flash``, ``make flash`` will automatically rebuild anything which needs it. + + +Compiling & Flashing Just the App +--------------------------------- + +After the initial flash, you may just want to build and flash just your app, not the bootloader and partition table: + +* ``make app`` - build just the app. +* ``make app-flash`` - flash just the app. + +``make app-flash`` will automatically rebuild the app if it needs it. + +There's no downside to reflashing the bootloader and partition table each time, if they haven't changed. + + +The Partition Table +------------------- + +Once you've compiled your project, the "build" directory will contain a binary file with a name like "my_app.bin". This is an ESP32 image binary that can be loaded by the bootloader. + +A single ESP32's flash can contain multiple apps, as well as many kinds of data (calibration data, filesystems, parameter storage, etc). For this reason, a partition table is flashed to offset 0x8000 in the flash. + +Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded. + +The simplest way to use the partition table is to `make menuconfig` and choose one of the simple predefined partition tables: + +* "Single factory app, no OTA" +* "Factory app, two OTA definitions" + +In both cases the factory app is flashed at offset 0x10000. If you `make partition_table` then it will print a summary of the partition table. + +For more details about :doc:`partition tables <../api-guides/partition-tables>` and how to create custom variations, view the :doc:`documentation <../api-guides/partition-tables>`. + diff --git a/en/get-started/toolchain-setup-scratch.rst b/en/get-started/toolchain-setup-scratch.rst new file mode 100644 index 00000000..c5f2b5ae --- /dev/null +++ b/en/get-started/toolchain-setup-scratch.rst @@ -0,0 +1,25 @@ +.. _get-started-customized-setup: + +***************************** +Customized Setup of Toolchain +***************************** + +Instead of downloading binary toolchain from Espressif website (see :ref:`get-started-setup-toolchain`) you may build the toolchain yourself. + +If you can't think of a reason why you need to build it yourself, then probably it's better to stick with the binary version. However, here are some of the reasons why you might want to compile it from source: + +- if you want to customize toolchain build configuration +- if you want to use a different GCC version (such as 4.8.5) +- if you want to hack gcc or newlib or libstdc++ +- if you are curious and/or have time to spare +- if you don't trust binaries downloaded from the Internet + +In any case, here are the instructions to compile the toolchain yourself. + +.. toctree:: + :maxdepth: 1 + + windows-setup-scratch + linux-setup-scratch + macos-setup-scratch + diff --git a/en/index.rst b/en/index.rst new file mode 100644 index 00000000..6def313b --- /dev/null +++ b/en/index.rst @@ -0,0 +1,60 @@ +.. M5Stack documentation master file, created by + sphinx-quickstart on Sat Jul 21 01:10:30 2018. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +M5Stack's Documents +============================= + +Welcom to M5Stack Documents! + +The documentation has different language versions (`en:English`, `zh_CN:中文版`, `How to switch between languages? `). However, please refer to the English version if there is any discrepancy. + +The green arrows designate “more info” links leading to advanced sections about the described task. + +====================== ====================== ====================== +|Product Documents|_ |Get Started|_ |API Reference|_ +---------------------- ---------------------- ---------------------- +`Product Documents`_ `Get Started`_ `API Reference`_ +---------------------- ---------------------- ---------------------- +|M5Stack Forum|_ |M5Stack-awesome|_ |M5Stack-FAQ|_ +---------------------- ---------------------- ---------------------- +`M5Stack Forum`_ `M5Stack-awesome`_ `M5Stack-FAQ`_ +====================== ====================== ====================== + + +.. |Product Documents| image:: ../_static/pics/product-documents.jpg +.. _Product Documents: product-documents/index.html + +.. |Get Started| image:: ../_static/pics/get-started.jpg +.. _Get Started: get-started/index.html + + +.. |API Reference| image:: ../_static/pics/m5-api-reference.jpg +.. _API Reference: api-reference/index.html + +.. |M5Stack Forum| image:: ../_static/pics/m5stack-forum.jpg +.. _M5Stack Forum: index.html + +.. |M5Stack-awesome| image:: ../_static/pics/m5-awesome.jpg +.. _M5Stack-awesome: m5stack-awesome/index.html + +.. |M5Stack-FAQ| image:: ../_static/pics/FAQ.jpg +.. _M5Stack-FAQ: m5stack-faq/index.html + + + + +.. toctree:: + :hidden: + + Product Documents + Get Started + API Reference + M5Stack-FAQ + M5Stack-awesome + Copyrights + About + [语言/Languages] + +* :ref:`genindex` diff --git a/en/languages.rst b/en/languages.rst new file mode 100644 index 00000000..7772cb00 --- /dev/null +++ b/en/languages.rst @@ -0,0 +1,19 @@ +Switch Between Languages/切换语言 +================================= + +The documentation now has two language versions, however, please refer to the English version if there is any discrepancy. + +本文档现在有两种语言的版本，如有出入请以英文版本为准。 + +- English/英文 +- Chinese/中文 + +You can easily changed from one language to another by the panel on the sidebar like below. Just click on the **Read +the Docs** title button on the left-bottom conner if it is folded. + +如下图所示，你可使用边栏的面板进行语言的切换。如果该面板被折叠，点击左下角 **Read the Docs** 标题按钮来显示它。 + +.. image:: /../_static/choose_version.png + + + diff --git a/en/m5stack-awesome/M5Stack-SD-Updater/index.rst b/en/m5stack-awesome/M5Stack-SD-Updater/index.rst new file mode 100644 index 00000000..63080e22 --- /dev/null +++ b/en/m5stack-awesome/M5Stack-SD-Updater/index.rst @@ -0,0 +1,4 @@ +M5Stack-SD-Updater +******************* + + diff --git a/en/m5stack-awesome/M5Widgets/index.rst b/en/m5stack-awesome/M5Widgets/index.rst new file mode 100644 index 00000000..7639fc2b --- /dev/null +++ b/en/m5stack-awesome/M5Widgets/index.rst @@ -0,0 +1,3 @@ +M5Widgets +************* + diff --git a/en/m5stack-awesome/TFT_eSPI/index.rst b/en/m5stack-awesome/TFT_eSPI/index.rst new file mode 100644 index 00000000..12d61e3a --- /dev/null +++ b/en/m5stack-awesome/TFT_eSPI/index.rst @@ -0,0 +1,3 @@ +TFT_eSPI +************* + diff --git a/en/m5stack-awesome/awesome.rst b/en/m5stack-awesome/awesome.rst new file mode 100644 index 00000000..79b05960 --- /dev/null +++ b/en/m5stack-awesome/awesome.rst @@ -0,0 +1,67 @@ +Awesome +~~~~~~~ + +- `M5Stack-SD-Updater `__ + - Customizable menu system for M5Stack - loads apps from the Micro SD + card +- `TFT\_eSPI `__ - TFT library for + the ESP8266 and ESP32 that supports different driver chips +- `M5Widgets `__ - Widgets for + the M5Stack +- `M5StackSAM `__ - Simple + Applications Menu Arduino Library for M5Stack +- `cfGUI `__ - A simple GUI library for + M5Stack (ESP32) +- `GUIslice `__ - A + lightweight GUI framework suitable for embedded displays +- `M5ez `__ - The easy way to program on + the M5Stack +- `M5Stack MultiApp + Advanced `__ + - A M5Stack firmware made on PlatformIO +- `M5Stack ESP32 + Oscilloscope `__ + - A fully functional oscilloscope based on ESP32 M5Stack +- `M5Stack-Avatar `__ - + An M5Stack library for rendering avatar faces +- `M5Stack\_CrackScreen `__ + - Crack your M5Stack!! +- `M5\_Shuttle\_Run `__ - + M5\_Shuttle\_Run +- `nixietubeM5 `__ - (Fake) + Nixie Tube Display on a M5Stack +- `M5Stack\_BTCTicker `__ + - A small Bitcoin price ticker using an M5Stack (ESP32) and the + Coindesk API +- `M5Stack\_ETHPrice `__ + - Dependence on example Wifi Setting to get ETH Price from Maicoin +- `M5Stack-PacketMonitor `__ + - M5Stack ESP32 Packet Monitor +- `M5-FFT `__ - Graphic + Equalizer on the M5Stack platform +- `M5Stack\_ESP32\_radio `__ + - Playing mp3 stream out of internet using M5Stack prototype +- `mp3-player-m5stack `__ + - MP3 player for M5Stack +- `ArduinoWiFiPhotoBackup `__ + - M5STACK Arduino WiFi Photo Backup device +- `M5StackHIDCtrlAltDel `__ + - You can send ctrl+alt+del to your PC from M5Stack +- `M5Stack Markdown Web + Server `__ + - Markdown & icons loaded from an Micro SD card/TF card to run a web + page +- `M5Stack-Tetris `__ + - Tetris for M5Stack Ported to M5Stack by macsbug - + https://macsbug.wordpress.com/ +- `M5Stack\_FlappyBird\_game `__ + - M5Stack FlappyBird Playable +- `M5Stack-SpaceShooter `__ + - Space Invaders knock-off for M5Stack +- `M5Stack-Pacman-JoyPSP `__ + - Pacman on M5Stack/PSP Joypad, with sounds +- `M5Stack-Thermal-Camera `__ + - M5Stack Thermal Camera with AMG8833 thermal sensor +- `M5Stack-3DPrintFiles `__ + - Links to files for 3D printing custom case parts for the M5Stack + diff --git a/en/m5stack-awesome/index.rst b/en/m5stack-awesome/index.rst new file mode 100644 index 00000000..a477e31c --- /dev/null +++ b/en/m5stack-awesome/index.rst @@ -0,0 +1,103 @@ +**************** +M5Stack-awesome +**************** + +.. toctree:: + :maxdepth: 3 + :hidden: + + M5Stack-SD-Updater + TFT_eSPI + M5Widgets + M5StackSAM + cfGUI + GUIslice + M5ez + M5Stack MultiApp Advanced + M5Stack ESP32 Oscilloscope + M5Stack-Avatar + M5Stack_CrackScreen + M5_Shuttle_Run + nixietubeM5 + M5Stack_BTCTicker + M5Stack_ETHPrice + M5Stack-PacketMonitor + M5-FFT + M5Stack_ESP32_radio + mp3-player-m5stack + ArduinoWiFiPhotoBackup + M5StackHIDCtrlAltDel + M5Stack Markdown Web + Server + M5Stack-Tetris + M5Stack_FlappyBird_game + M5Stack-SpaceShooter + M5Stack-Pacman-JoyPSP + M5Stack-Thermal-Camera + M5Stack-3DPrintFiles + + +- `M5Stack-SD-Updater `__ + - Customizable menu system for M5Stack - loads apps from the Micro SD + card +- `TFT\_eSPI `__ - TFT library for + the ESP8266 and ESP32 that supports different driver chips +- `M5Widgets `__ - Widgets for + the M5Stack +- `M5StackSAM `__ - Simple + Applications Menu Arduino Library for M5Stack +- `cfGUI `__ - A simple GUI library for + M5Stack (ESP32) +- `GUIslice `__ - A + lightweight GUI framework suitable for embedded displays +- `M5ez `__ - The easy way to program on + the M5Stack +- `M5Stack MultiApp + Advanced `__ + - A M5Stack firmware made on PlatformIO +- `M5Stack ESP32 + Oscilloscope `__ + - A fully functional oscilloscope based on ESP32 M5Stack +- `M5Stack-Avatar `__ - + An M5Stack library for rendering avatar faces +- `M5Stack\_CrackScreen `__ + - Crack your M5Stack!! +- `M5\_Shuttle\_Run `__ - + M5\_Shuttle\_Run +- `nixietubeM5 `__ - (Fake) + Nixie Tube Display on a M5Stack +- `M5Stack\_BTCTicker `__ + - A small Bitcoin price ticker using an M5Stack (ESP32) and the + Coindesk API +- `M5Stack\_ETHPrice `__ + - Dependence on example Wifi Setting to get ETH Price from Maicoin +- `M5Stack-PacketMonitor `__ + - M5Stack ESP32 Packet Monitor +- `M5-FFT `__ - Graphic + Equalizer on the M5Stack platform +- `M5Stack\_ESP32\_radio `__ + - Playing mp3 stream out of internet using M5Stack prototype +- `mp3-player-m5stack `__ + - MP3 player for M5Stack +- `ArduinoWiFiPhotoBackup `__ + - M5STACK Arduino WiFi Photo Backup device +- `M5StackHIDCtrlAltDel `__ + - You can send ctrl+alt+del to your PC from M5Stack +- `M5Stack Markdown Web + Server `__ + - Markdown & icons loaded from an Micro SD card/TF card to run a web + page +- `M5Stack-Tetris `__ + - Tetris for M5Stack Ported to M5Stack by macsbug - + https://macsbug.wordpress.com/ +- `M5Stack\_FlappyBird\_game `__ + - M5Stack FlappyBird Playable +- `M5Stack-SpaceShooter `__ + - Space Invaders knock-off for M5Stack +- `M5Stack-Pacman-JoyPSP `__ + - Pacman on M5Stack/PSP Joypad, with sounds +- `M5Stack-Thermal-Camera `__ + - M5Stack Thermal Camera with AMG8833 thermal sensor +- `M5Stack-3DPrintFiles `__ + - Links to files for 3D printing custom case parts for the M5Stack + diff --git a/en/m5stack-awesome/lcd.rst b/en/m5stack-awesome/lcd.rst new file mode 100644 index 00000000..913a225d --- /dev/null +++ b/en/m5stack-awesome/lcd.rst @@ -0,0 +1,231 @@ +Display Module +-------------- + +Methods +~~~~~~~ + +1.lcd.setRotation(2) +^^^^^^^^^^^^^^^^^^^^ + +***Description:*** ***Parament:*** ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.setRotation(2) + +2.lcd.setColor(foreground\_color[,background\_color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Set the default foreground/background color +***Parament:*** ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.setColor(lcd.RED) + lcd.setColor(lcd.ORANGE, LCD.DARKCYAN) + +3.lcd.setTextColor(foreground\_color[,background\_color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Set the default foreground/background color for +text ***Parament:*** \* ***color：*** color values are given as 24 bit +integer numbers, 8-bit per color ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.setTextColor(lcd.PINK) + lcd.setTextColor(lcd.ORANGE, LCD.DARKCYAN) + +4.lcd.fillScreen(color) +^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Fill the screen with the given color +***Parament:*** \* ***color：*** color values are given as 24 bit +integer numbers, 8-bit per color ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.fillScreen(lcd.color565(0x00, 0x00, 0x00)) + +5.lcd.drawPixel(x, y [,color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Draw the pixel at position **(x,y)** *Note:* +　　If color is not given, current foreground color is used +***Parament:*** \* ***color：*** color values are given as 24 bit +integer numbers, 8-bit per color ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.drawPixel(22,22,lcd.RED)   + +6.lcd.drawLine(x, y, x1, y1 [,color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Draw the line from point **(x,y)** to point +**(x1,y1)** *Note:* 　　If color is not given, current foreground color +is used ***Parament:*** \* ***color：*** color values are given as 24 +bit integer numbers, 8-bit per color ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.drawLine(0,0,lcd.WHITE)  + +7.lcd.drawTriangle(x, y, x1, y1, x2, y2 [,color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Draw the triangel between points **(x,y)**, +**(x1,y1)** and **(x2,y2)** *Note:* 　　If color is not given, current +foreground color is used 　 ***Parament:*** \* ***color：*** color +values are given as 24 bit integer numbers, 8-bit per color +***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.drawTriangle(22,22,69,98,51,22,lcd.RED) + +8.lcd.fillTriangle(x, y, x1, y1, x2, y2 [,color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Fill the triangel between points **(x,y)**, +**(x1,y1)** and **(x2,y2)** *Note:* 　　If **color** is not given, +triangle will be filled in current foreground color ***Parament:*** \* +***color：*** color values are given as 24 bit integer numbers, 8-bit +per color ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.fillTriangle(122,122,169,198,151,182,lcd.RED) + +　 #### 9.lcd.drawCircle(x, y, r [,color]) ***Description:*** 　　Draw +the circle with center at **(x,y)** and radius **r** *Note:* 　　If +**color** is not given, current foreground color is used + +***Parament:*** \* ***r:*** the radius of circle \* ***color：*** color +values are given as 24 bit integer numbers, 8-bit per color +***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.drawCircle(180,180,10,lcd.BLUE)  + +10.lcd.fillCircle(x, y, r [,color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Fill the circle with center at **(x,y)** and +radius **r** *Note:* 　　If **color** is not given, current foreground +color will be used + +***Parament:*** \* ***r:*** the radius of circle \* ***color：*** color +values are given as 24 bit integer numbers, 8-bit per color +***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.fillcircle(100,100,10,lcd.BLUE)  + +11.lcd.drawRect(x, y, width, height, [,color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Draw the rectangle from the upper left point at +**(x,y)** and width **width** and height **height** *Note:* 　　If +**color** is not given, rectangle will be drawn in current foreground +color ***Parament:*** \* ***width:*** optional, default=240, display +phisical width in pixels (display's smaller dimension). \* ***height:*** +optional, default=320, display phisical height in pixels (display's +larger dimension). \* ***color：*** color values are given as 24 bit +integer numbers, 8-bit per color ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.drawRect(180,12,122,10,lcd.BLUE) + +12.lcd.fillRect(x, y, width, height, [,color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Fill the rectangle from the upper left point at +**(x,y)** and width **width** and height **height** *Note:* 　　If +**fillcolor** is not given, rectangle will be filled in current +foreground color ***Parament:*** \* ***width:*** optional, default=240, +display phisical width in pixels (display's smaller dimension). \* +***height:*** optional, default=320, display phisical height in pixels +(display's larger dimension). \* ***color：*** color values are given as +24 bit integer numbers, 8-bit per color ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.fillRect(180,30,122,10,lcd.BLUE) + +13.lcd.drawRoundRect(x, y, width, height, r [,color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Draw the rectangle with rounded corners from the +upper left point at *(x,y)* and width **width** and height **height**. +Corner radius is given by **r** argument *Note:* 　　If *color* is not +given, current foreground color will be used ***Parament:*** \* +***width:*** optional, default=240, display phisical width in pixels +(display's smaller dimension) \* ***height:*** optional, default=320, +display phisical height in pixels (display's larger dimension). \* +***r:*** the radius of circle \* ***color：*** color values are given as +24 bit integer numbers, 8-bit per color ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.drawRoundRect(180,50,122,10,4,lcd.BLUE)  + +14.lcd.fillRoundRect(x, y, width, height, r [,color]) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Fill the rectangle with rounded corners from the +upper left point at *(x,y)* and width **width** and height **height**. +Corner radius is given by **r** argument *Note:* 　　If **color** is not +given, current foreground color will be used ***Parament:*** \* +***width:*** optional, default=240, display phisical width in pixels +(display's smaller dimension) \* ***height:*** optional, default=320, +display phisical height in pixels (display's larger dimension). \* +***r:*** the radius of circle \* ***color：*** color values are given as +24 bit integer numbers, 8-bit per color ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.fillRoundRect(180,70,122,10,4,lcd.BLUE)  + +15.lcd.print('text',x,y) +^^^^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Print the **text** at position **(x,y)** +***Parament:*** + +***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.print('this is a print text function', 80, 80) + +16.lcd.clear([color]) +^^^^^^^^^^^^^^^^^^^^^ + +***Description:*** 　　Clear the screen with default background color or +specific color if given ***Parament:*** \* ***color：*** color values +are given as 24 bit integer numbers, 8-bit per color ***Example:*** + +.. code:: python + + #The M5Stack Core LCD has been initialized + lcd.clear() + diff --git a/en/m5stack-faq/M5Stack-Core/index.rst b/en/m5stack-faq/M5Stack-Core/index.rst new file mode 100644 index 00000000..426c8a5b --- /dev/null +++ b/en/m5stack-faq/M5Stack-Core/index.rst @@ -0,0 +1,3 @@ +M5Stack-Core FAQ +***************** + diff --git a/en/m5stack-faq/M5Stack-Module/index.rst b/en/m5stack-faq/M5Stack-Module/index.rst new file mode 100644 index 00000000..f2c8d741 --- /dev/null +++ b/en/m5stack-faq/M5Stack-Module/index.rst @@ -0,0 +1,3 @@ +M5Stack-Module FAQ +******************* + diff --git a/en/m5stack-faq/index.rst b/en/m5stack-faq/index.rst new file mode 100644 index 00000000..6e01b311 --- /dev/null +++ b/en/m5stack-faq/index.rst @@ -0,0 +1,9 @@ +************* +M5Stack-FAQ +************* + +.. toctree:: + :maxdepth: 2 + + M5Stack-Core + M5Stack-Module \ No newline at end of file diff --git a/en/product-documents/bots/BALA.md b/en/product-documents/bots/BALA.md new file mode 100644 index 00000000..d2650958 --- /dev/null +++ b/en/product-documents/bots/BALA.md @@ -0,0 +1,46 @@ +# M5Stack BALA + +## DESCRIPTION + +The M5Stack BALA is a balance bot based on M5Stack FIRE. You can even program The M5Stack BALA through MicroPython with few code + +## FEATURES + +- Programming Support + + Python +- Compatible LEGO +- POGO Pin +- TF Card Support + +## PARAMETER + +Model | M5Stack FIRE +---|--- +ESP32 | 240MHz dual core, 600 DMIPS, 4MB SRAM, Wi-Fi, dual mode Bluetooth +Flash | 16M-Bytes +Input | 5V @ 500mA +Interface | TypeC x 1, GROVE(I2C+I/0+UART), Pogo Pin x 1 +LCD | 2 inch, 320x240 Colorful TFT LCD, ILI9342 +Speaker | 1W-0928 +Microphone | MEMS Analog BSE3729 Microphone +LED | SK6812 3535 RGB LED x 10 +MEMS | MPU6050, MAG3110 +Battery | 550mAh @ 3.7V, inside +Op.Temp. | 32°F to 104°F ( 0°C to 40°C ) +Size | 54 x 54 x 21 mm +C.A.S.E | Plastic ( PC ) +Weight | 56g + +## INCLUDES + +- 1x M5Stack BALA +- 1x Motor Driver +- 2x N20(Encoder included) +- Type-C USB Cable + + +## DOCUMENTS +- [Datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_cn.pdf) (ESP32) +- [GitHub](https://github.com/m5stack/M5Bala) +- [QuickStart](https://github.com/m5stack/M5Bala) +- [Example](https://github.com/m5stack/M5Bala) \ No newline at end of file diff --git a/en/product-documents/index.rst b/en/product-documents/index.rst new file mode 100644 index 00000000..f8215b2d --- /dev/null +++ b/en/product-documents/index.rst @@ -0,0 +1,43 @@ +****************** +Product Documents +****************** + +IOT Development Kit +~~~~~~~~~~~~~~~~~~~ + + +- `M5Stack M5GO `__ + + + + +M5Stack Core +~~~~~~~~~~~~~~~~~~~ +.. toctree:: + :maxdepth: 1 + + M5Stack BASIC + M5Stack GRAY + M5Stack FIRE + M5Stack PANDA + M5Stack FACES + M5Stack PLC + +Modules +~~~~~~~~~~~~~~~~~~~ +.. toctree:: + :maxdepth: 1 + + ESP32CAM + M5Stack GPS Module + M5Stack LORA Module + M5Stack SIM800 Module + M5Stack BATTERY Module + +Tools +~~~~~~~~~~~~~~~~~~~ +.. toctree:: + :maxdepth: 1 + + ESP32CAM + diff --git a/en/product-documents/m5stack-core/index.rst b/en/product-documents/m5stack-core/index.rst new file mode 100644 index 00000000..b2126847 --- /dev/null +++ b/en/product-documents/m5stack-core/index.rst @@ -0,0 +1,14 @@ +M5Stack Core Description +************************* + +.. toctree:: + :maxdepth: 3 + + M5Stack BASIC + M5Stack GRAY + M5Stack FIRE + M5Stack PANDA + M5Stack FACES + M5Stack PLC + +Example code for this API section is provided in directory of ESP-IDF examples. diff --git a/en/product-documents/m5stack-core/m5stack_basic.rst b/en/product-documents/m5stack-core/m5stack_basic.rst new file mode 100644 index 00000000..bc90a1f2 --- /dev/null +++ b/en/product-documents/m5stack-core/m5stack_basic.rst @@ -0,0 +1,69 @@ +M5Stack BASIC +============= + +DESCRIPTION +----------- + +The M5Stack BASIC is a development kit based on ESP32 chip. You can even +program The M5Stack BASIC through Blockly, Arduino or MicroPython. + +The M5Stack BASIC equips the ESP32 with everything necessary to program, +and a TFT LCD, so you can create a 3D remote gesture controller, a +simple "Leap Motion" via M5Stack BASIC in a day in stead of couple weeks +and so on. + +FEATURES +-------- + +- Programming Support +- Arduino +- ESP-IDF +- MicroPython +- TF Card Support + +PARAMETER +--------- + ++-------------+-----------------------------------------------------------------+ +| Model | M5Stack BASIC | ++=============+=================================================================+ +| ESP32 | 240MHz dual core, 600 DMIPS, 520K, Wi-Fi, dual mode Bluetooth | ++-------------+-----------------------------------------------------------------+ +| Flash | 4M-Bytes | ++-------------+-----------------------------------------------------------------+ +| Input | 5V @ 500mA | ++-------------+-----------------------------------------------------------------+ +| Interface | TypeC x 1, GROVE(I2C+I/0+UART) x 1 | ++-------------+-----------------------------------------------------------------+ +| LCD | 2 inch, 320x240 Colorful TFT LCD, ILI9342 | ++-------------+-----------------------------------------------------------------+ +| Speaker | 1W-0928 | ++-------------+-----------------------------------------------------------------+ +| Battery | 150mAh @ 3.7V, inside | ++-------------+-----------------------------------------------------------------+ +| Op.Temp. | 32°F to 104°F ( 0°C to 40°C ) | ++-------------+-----------------------------------------------------------------+ +| Size | 54 x 54 x 12.5 mm | ++-------------+-----------------------------------------------------------------+ +| C.A.S.E | Plastic ( PC ) | ++-------------+-----------------------------------------------------------------+ +| Weight | 120g with bottom, 100g only core | ++-------------+-----------------------------------------------------------------+ + +INCLUDES +-------- + +- 1x M5Stack BASIC +- 1x M5Stack BASIC Bottom +- Type-C USB Cable +- User Manual + +DOCUMENTS +--------- + +- `Schematic `__ +- `Example `__ +- `Datasheet `__ + (ESP32) +- `GitHub `__ + diff --git a/en/product-documents/m5stack-core/m5stack_faces.rst b/en/product-documents/m5stack-core/m5stack_faces.rst new file mode 100644 index 00000000..b3e2159e --- /dev/null +++ b/en/product-documents/m5stack-core/m5stack_faces.rst @@ -0,0 +1,92 @@ +M5Stack FACES +============= + +DESCRIPTION +----------- + +The M5Stack FACES is a development kit based on ESP32 chip compatible +with three different KeyBoards( *26 letters KeyBoard, Gameboy KeyBoard +and Calculator KeyBoard*). + +You can even program The M5Stack FACES through Blockly, Arduino or +MicroPython. Absolutely, you can DIY many classify GameBoy games as you +like, such as Super Mario, Tetris and so on.You also make a remotely +controlled calculator, or a Somatosensory game remote controller. + +FEATURES +-------- + +- Programming Support +- Blockly +- Arduino +- Python +- Compatible LEGO +- Support Nintendo emulator +- TF Card Support + +PARAMETER +--------- + ++--------------+---------------------------------------------------------------------+ +| Model | M5Stack GrayCore | ++==============+=====================================================================+ +| ESP32 | 240MHz dual core, 600 DMIPS, 4MB SRAM, Wi-Fi, dual mode Bluetooth | ++--------------+---------------------------------------------------------------------+ +| Flash | 16M-Bytes | ++--------------+---------------------------------------------------------------------+ +| Input | 5V @ 500mA | ++--------------+---------------------------------------------------------------------+ +| Interface | TypeC x 1, GROVE(I2C+I/0+UART), Pogo Pin x 1 | ++--------------+---------------------------------------------------------------------+ +| Extend Pin | Bus/GPIO Extend | ++--------------+---------------------------------------------------------------------+ +| LCD | 2 inch, 320x240 Colorful TFT LCD, ILI9342 | ++--------------+---------------------------------------------------------------------+ +| Speaker | 1W-0928 | ++--------------+---------------------------------------------------------------------+ +| MEMS | MPU9250 | ++--------------+---------------------------------------------------------------------+ +| Battery | 650mAh @ 3.7V, inside | ++--------------+---------------------------------------------------------------------+ +| Op.Temp. | 32F to 104F ( 0C to 40C ) | ++--------------+---------------------------------------------------------------------+ +| Size | 54 x 54 x 21 mm | ++--------------+---------------------------------------------------------------------+ +| C.A.S.E | Plastic ( PC ) | ++--------------+---------------------------------------------------------------------+ +| Weight | 56g? | ++--------------+---------------------------------------------------------------------+ + +INCLUDES +-------- + +- 1x M5Stack GrayCore +- 1x KeyBoard +- 1x Gameboy +- 1x Calculator +- 1x FaceBottom +- 1x CHG base +- Type-C USB Cable +- User Manual + +Applications +------------ + +- DIY Gameboy Games: +- Nintendo emulator +- Tetris +- DIY Calculator +- DIY PocketComputer + +DOCUMENTS +--------- + +- `Schematic `__ +- `Example `__ +- `Datasheet `__ + (ESP32) +- `Datasheet `__ + (MPU9250) +- `M5Stack-nesemu `__ +- `GitHub `__ + diff --git a/en/product-documents/m5stack-core/m5stack_fire.rst b/en/product-documents/m5stack-core/m5stack_fire.rst new file mode 100644 index 00000000..b8cd31ae --- /dev/null +++ b/en/product-documents/m5stack-core/m5stack_fire.rst @@ -0,0 +1,83 @@ +M5Stack FIRE +============ + +DESCRIPTION +----------- + +The M5Stack FIRE is a development kit based on ESP32 chip. You can even +program The M5Stack FIRE through Blockly, Arduino or MicroPython. + +The M5Stack FIRE equips the ESP32 with everything necessary to program, +run and develop on the wonderchip. It also features a Six-Axis (Gyro + +Accelerometer) MEMS (MPU-6050), a 3-Axis Digital Magnetometer (MAG3110) +and a TFT LCD, so you can create a 3D remote gesture controller, a +simple "Leap Motion" via M5Stack FIRE in a day in stead of couple weeks +and so on. + +FEATURES +-------- + +- Programming Support +- Blockly +- Arduino +- Python +- Compatible LEGO +- TF Card Support + +PARAMETER +--------- + ++--------------+---------------------------------------------------------------------+ +| Model | M5Stack FIRE | ++==============+=====================================================================+ +| ESP32 | 240MHz dual core, 600 DMIPS, 4MB SRAM, Wi-Fi, dual mode Bluetooth | ++--------------+---------------------------------------------------------------------+ +| Flash | 16M-Bytes | ++--------------+---------------------------------------------------------------------+ +| Input | 5V @ 500mA | ++--------------+---------------------------------------------------------------------+ +| Interface | TypeC x 1, GROVE(I2C+I/0+UART), Pogo Pin x 1 | ++--------------+---------------------------------------------------------------------+ +| LCD | 2 inch, 320x240 Colorful TFT LCD, ILI9342 | ++--------------+---------------------------------------------------------------------+ +| Speaker | 1W-0928 | ++--------------+---------------------------------------------------------------------+ +| Microphone | MEMS Analog BSE3729 Microphone | ++--------------+---------------------------------------------------------------------+ +| LED | SK6812 3535 RGB LED x 10 | ++--------------+---------------------------------------------------------------------+ +| MEMS | MPU6050, MAG3110 | ++--------------+---------------------------------------------------------------------+ +| Battery | 550mAh @ 3.7V, inside | ++--------------+---------------------------------------------------------------------+ +| Op.Temp. | 32°F to 104°F ( 0°C to 40°C ) | ++--------------+---------------------------------------------------------------------+ +| Size | 54 x 54 x 21 mm | ++--------------+---------------------------------------------------------------------+ +| C.A.S.E | Plastic ( PC ) | ++--------------+---------------------------------------------------------------------+ +| Weight | 56g | ++--------------+---------------------------------------------------------------------+ + +INCLUDES +-------- + +- 1x M5Stack FIRE +- 1x M5GO Bottom +- 1x M5GO CHG BASE +- Type-C USB Cable +- User Manual + +DOCUMENTS +--------- + +- `Schematic `__ +- `Example `__ +- `Datasheet `__ + (ESP32) +- `Datasheet `__ + (MPU6050) +- `Datasheet `__ + (MAG3110) +- `GitHub `__ + diff --git a/en/product-documents/m5stack-core/m5stack_gray.rst b/en/product-documents/m5stack-core/m5stack_gray.rst new file mode 100644 index 00000000..b08e28cd --- /dev/null +++ b/en/product-documents/m5stack-core/m5stack_gray.rst @@ -0,0 +1,74 @@ +M5Stack GRAY +============ + +DESCRIPTION +----------- + +The M5Stack GRAY is a development kit based on ESP32 chip. You can even +program The M5Stack GRAY through Blockly, Arduino or MicroPython. + +The M5Stack GRAY equips the ESP32 with everything necessary to program, +run and develop on the wonderchip. It also features a Six-Axis (Gyro + +Accelerometer), 3-Axis Digital Magnetometer, MEMS(MPU9250), and a TFT +LCD, so you can create a 3D remote gesture controller, a simple "Leap +Motion" via M5Stack GRAY in a day in stead of couple weeks and so on. + +FEATURES +-------- + +- Programming Support +- Arduino +- ESP-IDF +- MicroPython +- TF Card Support + +PARAMETER +--------- + ++-------------+-----------------------------------------------------------------+ +| Model | M5Stack GRAY | ++=============+=================================================================+ +| ESP32 | 240MHz dual core, 600 DMIPS, 520K, Wi-Fi, dual mode Bluetooth | ++-------------+-----------------------------------------------------------------+ +| Flash | 4M-Bytes | ++-------------+-----------------------------------------------------------------+ +| Input | 5V @ 500mA | ++-------------+-----------------------------------------------------------------+ +| Interface | TypeC x 1, GROVE(I2C+I/0+UART) x 1 | ++-------------+-----------------------------------------------------------------+ +| LCD | 2 inch, 320x240 Colorful TFT LCD, ILI9342 | ++-------------+-----------------------------------------------------------------+ +| Speaker | 1W-0928 | ++-------------+-----------------------------------------------------------------+ +| MEMS | MPU9250 | ++-------------+-----------------------------------------------------------------+ +| Battery | 150mAh @ 3.7V, inside | ++-------------+-----------------------------------------------------------------+ +| Op.Temp. | 32°F to 104°F ( 0°C to 40°C ) | ++-------------+-----------------------------------------------------------------+ +| Size | 54 x 54 x 12.5 mm | ++-------------+-----------------------------------------------------------------+ +| C.A.S.E | Plastic ( PC ) | ++-------------+-----------------------------------------------------------------+ +| Weight | 120g with bottom, 100g only core | ++-------------+-----------------------------------------------------------------+ + +INCLUDES +-------- + +- 1x M5Stack GRAY +- 1x M5Stack Core Bottom +- Type-C USB Cable +- User Manual + +DOCUMENTS +--------- + +- `Schematic `__ +- `Example `__ +- `Datasheet `__ + (ESP32) +- `Datasheet `__ + (MPU9250) +- `GitHub `__ + diff --git a/en/product-documents/m5stack-core/m5stack_panda.rst b/en/product-documents/m5stack-core/m5stack_panda.rst new file mode 100644 index 00000000..c4e03ef5 --- /dev/null +++ b/en/product-documents/m5stack-core/m5stack_panda.rst @@ -0,0 +1,69 @@ +M5Stack PANDA +============= + +DESCRIPTION +----------- + +The M5Stack PANDA is a development kit based on ESP32 chip. You can even +program The M5Stack PANDA through Blockly, Arduino or MicroPython. + +The M5Stack PANDA equips the ESP32 with everything necessary to program, +and a TFT LCD, so you can create a 3D remote gesture controller, a +simple "Leap Motion" via M5Stack PANDA in a day in stead of couple weeks +and so on. + +FEATURES +-------- + +- Programming Support +- Arduino +- ESP-IDF +- MicroPython +- TF Card Support + +PARAMETER +--------- + ++-------------+-----------------------------------------------------------------+ +| Model | M5Stack PANDA | ++=============+=================================================================+ +| ESP32 | 240MHz dual core, 600 DMIPS, 520K, Wi-Fi, dual mode Bluetooth | ++-------------+-----------------------------------------------------------------+ +| Flash | 4M-Bytes | ++-------------+-----------------------------------------------------------------+ +| Input | 5V @ 500mA | ++-------------+-----------------------------------------------------------------+ +| Interface | TypeC x 1, GROVE(I2C+I/0+UART) x 1 | ++-------------+-----------------------------------------------------------------+ +| LCD | 2 inch, 320x240 Colorful TFT LCD, ILI9342 | ++-------------+-----------------------------------------------------------------+ +| Speaker | 1W-0928 | ++-------------+-----------------------------------------------------------------+ +| Battery | 150mAh @ 3.7V, inside | ++-------------+-----------------------------------------------------------------+ +| Op.Temp. | 32°F to 104°F ( 0°C to 40°C ) | ++-------------+-----------------------------------------------------------------+ +| Size | 54 x 54 x 12.5 mm | ++-------------+-----------------------------------------------------------------+ +| C.A.S.E | Plastic ( PC ) | ++-------------+-----------------------------------------------------------------+ +| Weight | 120g with bottom, 100g only core | ++-------------+-----------------------------------------------------------------+ + +INCLUDES +-------- + +- 1x M5Stack PANDA +- 1x M5Stack BASIC Bottom +- Type-C USB Cable +- User Manual + +DOCUMENTS +--------- + +- `Schematic `__ +- `Example `__ +- `Datasheet `__ + (ESP32) +- `GitHub `__ + diff --git a/en/product-documents/m5stack-core/m5stack_plc.rst b/en/product-documents/m5stack-core/m5stack_plc.rst new file mode 100644 index 00000000..db1dd5f8 --- /dev/null +++ b/en/product-documents/m5stack-core/m5stack_plc.rst @@ -0,0 +1,48 @@ +M5Stack PLC Module +================== + +DESCRIPTION +----------- + +The M5Stack PLC Module is a prototye industrial board, including RS484 +adapter and electricity meter module. + +With DC9~24V power input, PLC-Proto motherboard reserved 6Pin or 4Pin +relay output, digital input, communication interface etc. + +FEATURES +-------- + +- Free DIY +- Programmable Logic Controller +- Individual package weight: 0.1kg (0.22lb.) +- Package size: 5cm \* 5cm \* 5cm (1.97in \* 1.97in \* 1.97in) + +INCLUDES +-------- + +- 1x PLC-Proto Broad +- 1x RS485 module +- 1x PLC Plastic Enclosure +- 1x Slide Guide +- 1x Magnet +- 1x 6 Pin 3.96 Pitch Terminal +- 1x 4 Pin 3.96 Pitch Terminal +- 3x Hex Key +- 7x Electrical Terminal +- 1x Sticker + +Applications +------------ + +- Programmable Logic Controller +- Programmable Motion Controller +- Digital Operation Processor +- Strong Electric Controller + +DOCUMENTS +--------- + +- `WebSite `__ +- `GitHub `__ + diff --git a/en/product-documents/modules/esp32cam.md b/en/product-documents/modules/esp32cam.md new file mode 100644 index 00000000..2ec76483 --- /dev/null +++ b/en/product-documents/modules/esp32cam.md @@ -0,0 +1,53 @@ +# ESP32CAM + +## DESCRIPTION + +The ESP32CAM is a tiny module based on ESP32 chip and OV2640. You can even program the ESP32CAM through the ESP-IDF by installing the ESP32 Core. + +The ESP32CAM equips the ESP32 with everything necessary to program, run and develop on the wonderful chip. It also features a LiPo charger (IP5306) , so your ESP32CAM project can be battery-powered and truly wireless. Additionally, the board reserved the MPU6050,BME280 and an analog MIC. + + +## INCLUDES + +- 1x M5 Camera +- 1x Type-C USB v + + +## FEATURES + +- ESP32 specifications + + Dual-core Tensilica LX6 microprocessor + + Up to 240MHz clock frequency + + 520kB internal SRAM + + 4MB Flash memory + + Integrated 802.11 BGN WiFi transceiver + + Integrated dual-mode Bluetooth (classic and BLE) + + Hardware accelerated encryption (AES, SHA2, ECC, RSA-4096) +- CP2104 USB TTL +- OV2640 sensor + - Output Formats(8-bit): + + YUV(422/420)/YCbCr422 + + RGB565/555 + + 8-bit compressed data + + 8-/10-bit Raw RGB data + - Maximum Image Transfer Rate + + UXGA/SXGA: 15fps + + SVGA: 30fps + + CIF: 60fps + - Scan Mode: Progressive +- Camera specifications + + CCD size : 1/4inch + + Field of View : 78 degree + + Maxmium Pixel: 200W +- Sensor best resolution: 1600 * 1200 +- Dimension: 25mm x 24mm +- Weight: 5g + + +## DOCUMENTS +- [Schematic](https://github.com/m5stack/esp32-cam-demo/blob/m5cam/M5CAM-ESP32-A1-POWER.pdf) +- [Example](https://github.com/m5stack/esp32-cam-demo) +- [Datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_cn.pdf) (ESP32) +- [Datasheet](https://www.uctronics.com/download/cam_module/OV2640DS.pdf) (OV2640) +- [GitHub](https://github.com/m5stack/esp32-cam-demo) +- [HowToWork](https://github.com/watson8544/M5Stack-UserGuide/blob/master/ESP32CAM_UserGuide.md) diff --git a/en/product-documents/modules/esp32cam.rst b/en/product-documents/modules/esp32cam.rst new file mode 100644 index 00000000..970f372c --- /dev/null +++ b/en/product-documents/modules/esp32cam.rst @@ -0,0 +1,75 @@ +ESP32CAM +======== + +DESCRIPTION +----------- + +The ESP32CAM is a tiny module based on ESP32 chip and OV2640. You can +even program the ESP32CAM through the ESP-IDF by installing the ESP32 +Core. + +The ESP32CAM equips the ESP32 with everything necessary to program, run +and develop on the wonderful chip. It also features a LiPo charger +(IP5306) , so your ESP32CAM project can be battery-powered and truly +wireless. Additionally, the board reserved the MPU6050,BME280 and an +analog MIC. + +INCLUDES +-------- + +- 1x M5 Camera +- 1x Type-C USB v + +FEATURES +-------- + +- ESP32 specifications + + - Dual-core Tensilica LX6 microprocessor + - Up to 240MHz clock frequency + - 520kB internal SRAM + - 4MB Flash memory + - Integrated 802.11 BGN WiFi transceiver + - Integrated dual-mode Bluetooth (classic and BLE) + - Hardware accelerated encryption (AES, SHA2, ECC, RSA-4096) + +- CP2104 USB TTL +- OV2640 sensor + + - Output Formats(8-bit): + + - YUV(422/420)/YCbCr422 + - RGB565/555 + - 8-bit compressed data + - 8-/10-bit Raw RGB data + + - Maximum Image Transfer Rate + + - UXGA/SXGA: 15fps + - SVGA: 30fps + - CIF: 60fps + + - Scan Mode: Progressive + +- Camera specifications + + - CCD size : 1/4inch + - Field of View : 78 degree + - Maxmium Pixel: 200W + +- Sensor best resolution: 1600 \* 1200 +- Dimension: 25mm x 24mm +- Weight: 5g + +DOCUMENTS +--------- + +- `Schematic `__ +- `Example `__ +- `Datasheet `__ + (ESP32) +- `Datasheet `__ + (OV2640) +- `GitHub `__ +- `HowToWork `__ + diff --git a/en/product-documents/modules/index.rst b/en/product-documents/modules/index.rst new file mode 100644 index 00000000..88485c91 --- /dev/null +++ b/en/product-documents/modules/index.rst @@ -0,0 +1,14 @@ +M5Stack Module Description +*************************** + +.. toctree:: + :maxdepth: 3 + + ESP32CAM + M5Stack GPS Module + M5Stack LORA Module + M5Stack SIM800 Module + M5Stack BATTERY Module + + +Example code for this API section is provided in directory of ESP-IDF examples. diff --git a/en/product-documents/modules/m5stack_battery_module.rst b/en/product-documents/modules/m5stack_battery_module.rst new file mode 100644 index 00000000..ea0cb50e --- /dev/null +++ b/en/product-documents/modules/m5stack_battery_module.rst @@ -0,0 +1,25 @@ +M5Stack BATTERY Module +====================== + +DESCRIPTION +----------- + +The M5Stack BATTERY Module is module with 850mAh High-Capacity Battery. +User can create a portble device with any series of M5Stack Core and +M5Stack BATTERY Module easily. + +FEATURES +-------- + +- 850mAh High-Capacity Battery + +INCLUDES +-------- + +- 1x M5Stack BATTERY Module + +DOCUMENTS +--------- + +- `WebSite `__ + diff --git a/en/product-documents/modules/m5stack_gps_module.rst b/en/product-documents/modules/m5stack_gps_module.rst new file mode 100644 index 00000000..c7540a97 --- /dev/null +++ b/en/product-documents/modules/m5stack_gps_module.rst @@ -0,0 +1,43 @@ +M5Stack GPS Module +================== + +DESCRIPTION +----------- + +The M5Stack GPS Module is a module with small GPS module. The small GPS +module named UBLOX NEO-M8N. You can program it through Blockly, Arduino +or MicroPython after connected to any series of M5Stack Core. + +GPS module is built on the high performing u-blox M8 GNSS engine and +exhibit high performance and high sensitivity.And it can supply your +global positioning information even you in the wild and get lost. + +FEATURES +-------- + +- GPS NEO-M8N Module +- high-performance +- high-sensitivity +- Concurrent reception of up to 3 GNSS +- Industry leading –167 dBm navigation sensitivity + +INCLUDES +-------- + +- 1x M5Stack GPS Module +- 1x M5Stack Antenna + +Applications +------------ + +- Child positioning bracelet +- Logistics Tracking Management based on GPS + +DOCUMENTS +--------- + +- `WebSite `__ +- `Example `__ +- `GPS Info `__ (GPS) +- `GitHub `__ + diff --git a/en/product-documents/modules/m5stack_lora_module.rst b/en/product-documents/modules/m5stack_lora_module.rst new file mode 100644 index 00000000..e7197038 --- /dev/null +++ b/en/product-documents/modules/m5stack_lora_module.rst @@ -0,0 +1,60 @@ +M5Stack LORA Module +=================== + +DESCRIPTION +----------- + +The M5Stack LoRa Module is a module with small LoRa module named Ra-02. +You can program it after connected to any series of M5Stack Core through +Blockly, Arduino or MicroPython. + +M5Stack LoRa Module can be used for ultra-long distance spread spectrum +communication, and compatible FSK remote modulation and demodulation +quickly, to solve the traditional wireless design can not take into +account the distance, anti-interference and power consumption + +FEATURES +-------- + +- LoRa Module named RA-02 supply by Ai-Thinker +- Supports FSK, GFSK, MSK, GMSK, LoRa ™ and OOK modulation modes +- Receive sensitivity as low as -141 dBm +- Programmable bit rate up to 300Kbps +- Build-in Antenna + +INCLUDES +-------- + +- 1x M5Stack LoRa Module + +Applications +------------ + +- Automatic meter reading +- Home building automation +- Remote irrigation system + +DOCUMENTS +--------- + +- `WebSite `__ +- `Example `__ +- `LoRa Info `__ (LoRa) +- `GitHub `__ + +*NOTE* +~~~~~~ + +If your board LCD can't display or has some other problem, we suggest +you to add the two statements code followed by ``m5.begin();`` as shown +below + +.. code:: cpp + + m5.begin(); + pinMode(5,OUTPUT); + digitalWrite(5,HIGH); + +Because GPIO5 who has connected NSS pin of LoRa module need be pull-up +at the moment your board(or system) power on to prevent system's LCD +can't display. diff --git a/en/product-documents/modules/m5stack_sim800_module.rst b/en/product-documents/modules/m5stack_sim800_module.rst new file mode 100644 index 00000000..6564f94e --- /dev/null +++ b/en/product-documents/modules/m5stack_sim800_module.rst @@ -0,0 +1,49 @@ +M5Stack SIM800L Module +====================== + +DESCRIPTION +----------- + +The M5Stack SIM800L Module is a module with small SIM800L GSM/GPRS +module. You can program it after connected to any series of M5Stack Core +through Blockly, Arduino or MicroPython. + +SIM800L is a complete Quad-band GSM/GPRS solution. SIM800L moudle could +be connected with M5Stack Core via a serial port named USART2. +Absolutely, you also can change the serial port number with jumper by +your own. + +FEATURES +-------- + +- SIM800L Module +- Build-in Antenna +- 3.5 mm phone audio jack +- Microphone +- Parameter: +- GSM/GPRS +- support Quad-band 850/900/1800/1900MHz +- transmit Voice, SMS and data information with low power consumption +- Featur Bluetooth and Embedded AT + +INCLUDES +-------- + +- 1x M5Stack SIM800L Module + +Applications +------------ + +- Nitrogen dioxide alarm +- Automatic Web Spider SMS-notifier +- Remote meter reading system + +DOCUMENTS +--------- + +- `WebSite `__ +- `Example `__ +- `SIM800L Info `__ + (SIM800L) +- `GitHub `__ + diff --git a/en/product-documents/tools/esp32cam.rst b/en/product-documents/tools/esp32cam.rst new file mode 100644 index 00000000..880b79a0 --- /dev/null +++ b/en/product-documents/tools/esp32cam.rst @@ -0,0 +1,13 @@ +Mesh +===== + +Application Examples +-------------------- + +See directory of ESP-IDF examples that contains the following applications. + + +API Reference +-------------- + + diff --git a/en/product-documents/tools/index.rst b/en/product-documents/tools/index.rst new file mode 100644 index 00000000..2bd73372 --- /dev/null +++ b/en/product-documents/tools/index.rst @@ -0,0 +1,10 @@ +M5Stack Module Description +*************************** + +.. toctree:: + :maxdepth: 1 + + ESP32CAM + + +Example code for this API section is provided in directory of ESP-IDF examples. diff --git a/en/resources.rst b/en/resources.rst new file mode 100644 index 00000000..c7e48b62 --- /dev/null +++ b/en/resources.rst @@ -0,0 +1,14 @@ +********* +Resources +********* + +* The `m5stack.com forum `_ is a place to ask questions and find community resources. + +* Check the `M5Stack Arduino Issues `_ section on GitHub if you find a bug or have a feature request. Please check existing `M5Stack Arduino Issues `_ before opening a new one. + + + + + + + diff --git a/hello.md b/hello.md new file mode 100644 index 00000000..6d774529 --- /dev/null +++ b/hello.md @@ -0,0 +1,3 @@ +## hello world + +### test markdown diff --git a/index.rst b/index.rst new file mode 100644 index 00000000..c7b048f9 --- /dev/null +++ b/index.rst @@ -0,0 +1,39 @@ +.. M5Stack documentation master file, created by + sphinx-quickstart on Sat Jul 21 01:10:30 2018. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +M5Stack's Documents +========================= + + +The documentation has different language versions. However, please refer to the English version if there is any discrepancy. + +================== ================== ================== +|Get Started|_ |API Reference|_ |M5Stack-cookbook|_ +================== ================== ================== + +.. |Get Started| image:: ../_static/get-started.gif +.. _Get Started: get-started/index.html + + +.. toctree:: + :hidden: + + Get Started + API Reference + M5Stack Awesome + API Guides + Contribute + Resources + Copyrights + About + [语言/Languages] + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/zh_CN/resources.rst b/zh_CN/resources.rst new file mode 100644 index 00000000..320597ae --- /dev/null +++ b/zh_CN/resources.rst @@ -0,0 +1 @@ +.. include:: ../en/resources.rst \ No newline at end of file