diff --git a/.clang-format b/.clang-format new file mode 100644 index 00000000000..e608f4ed0b0 --- /dev/null +++ b/.clang-format @@ -0,0 +1,190 @@ +# Source: https://github.com/arduino/tooling-project-assets/tree/main/other/clang-format-configuration +--- +AccessModifierOffset: -2 +AlignAfterOpenBracket: Align +AlignArrayOfStructures: None +AlignConsecutiveAssignments: None +AlignConsecutiveBitFields: None +AlignConsecutiveDeclarations: None +AlignConsecutiveMacros: None +AlignEscapedNewlines: DontAlign +AlignOperands: Align +AlignTrailingComments: true +AllowAllArgumentsOnNextLine: true +AllowAllConstructorInitializersOnNextLine: true +AllowAllParametersOfDeclarationOnNextLine: true +AllowShortBlocksOnASingleLine: Always +AllowShortCaseLabelsOnASingleLine: true +AllowShortEnumsOnASingleLine: true +AllowShortFunctionsOnASingleLine: Empty +AllowShortIfStatementsOnASingleLine: AllIfsAndElse +AllowShortLambdasOnASingleLine: Empty +AllowShortLoopsOnASingleLine: true +AlwaysBreakAfterDefinitionReturnType: None +AlwaysBreakAfterReturnType: None +AlwaysBreakBeforeMultilineStrings: false +AlwaysBreakTemplateDeclarations: No +AttributeMacros: + - __capability +BasedOnStyle: LLVM +BinPackArguments: true +BinPackParameters: true +BitFieldColonSpacing: Both +BraceWrapping: + AfterCaseLabel: false + AfterClass: false + AfterControlStatement: Never + AfterEnum: false + AfterFunction: false + AfterNamespace: false + AfterObjCDeclaration: false + AfterStruct: false + AfterUnion: false + AfterExternBlock: false + BeforeCatch: false + BeforeElse: false + BeforeLambdaBody: false + BeforeWhile: false + IndentBraces: false + SplitEmptyFunction: true + SplitEmptyRecord: true + SplitEmptyNamespace: true +BreakAfterJavaFieldAnnotations: false +BreakBeforeBinaryOperators: NonAssignment +BreakBeforeBraces: Attach +BreakBeforeConceptDeclarations: false +BreakBeforeInheritanceComma: false +BreakBeforeTernaryOperators: true +BreakConstructorInitializers: BeforeColon +BreakConstructorInitializersBeforeComma: false +BreakInheritanceList: BeforeColon +BreakStringLiterals: false +ColumnLimit: 0 +CommentPragmas: '' +CompactNamespaces: false +ConstructorInitializerAllOnOneLineOrOnePerLine: false +ConstructorInitializerIndentWidth: 2 +ContinuationIndentWidth: 2 +Cpp11BracedListStyle: false +DeriveLineEnding: true +DerivePointerAlignment: true +DisableFormat: false +EmptyLineAfterAccessModifier: Leave +EmptyLineBeforeAccessModifier: Leave +ExperimentalAutoDetectBinPacking: false +FixNamespaceComments: false +ForEachMacros: + - foreach + - Q_FOREACH + - BOOST_FOREACH +IfMacros: + - KJ_IF_MAYBE +IncludeBlocks: Preserve +IncludeCategories: + - Regex: '^"(llvm|llvm-c|clang|clang-c)/' + Priority: 2 + SortPriority: 0 + CaseSensitive: false + - Regex: '^(<|"(gtest|gmock|isl|json)/)' + Priority: 3 + SortPriority: 0 + CaseSensitive: false + - Regex: '.*' + Priority: 1 + SortPriority: 0 + CaseSensitive: false +IncludeIsMainRegex: '' +IncludeIsMainSourceRegex: '' +IndentAccessModifiers: false +IndentCaseBlocks: true +IndentCaseLabels: true +IndentExternBlock: Indent +IndentGotoLabels: false +IndentPPDirectives: None +IndentRequires: true +IndentWidth: 2 +IndentWrappedFunctionNames: false +InsertTrailingCommas: None +JavaScriptQuotes: Leave +JavaScriptWrapImports: true +KeepEmptyLinesAtTheStartOfBlocks: true +LambdaBodyIndentation: Signature +Language: Cpp +MacroBlockBegin: '' +MacroBlockEnd: '' +MaxEmptyLinesToKeep: 100000 +NamespaceIndentation: None +ObjCBinPackProtocolList: Auto +ObjCBlockIndentWidth: 2 +ObjCBreakBeforeNestedBlockParam: true +ObjCSpaceAfterProperty: false +ObjCSpaceBeforeProtocolList: true +PPIndentWidth: -1 +PackConstructorInitializers: BinPack +PenaltyBreakAssignment: 1 +PenaltyBreakBeforeFirstCallParameter: 1 +PenaltyBreakComment: 1 +PenaltyBreakFirstLessLess: 1 +PenaltyBreakOpenParenthesis: 1 +PenaltyBreakString: 1 +PenaltyBreakTemplateDeclaration: 1 +PenaltyExcessCharacter: 1 +PenaltyIndentedWhitespace: 1 +PenaltyReturnTypeOnItsOwnLine: 1 +PointerAlignment: Right +QualifierAlignment: Leave +ReferenceAlignment: Pointer +ReflowComments: false +RemoveBracesLLVM: false +SeparateDefinitionBlocks: Leave +ShortNamespaceLines: 0 +SortIncludes: Never +SortJavaStaticImport: Before +SortUsingDeclarations: false +SpaceAfterCStyleCast: false +SpaceAfterLogicalNot: false +SpaceAfterTemplateKeyword: false +SpaceAroundPointerQualifiers: Default +SpaceBeforeAssignmentOperators: true +SpaceBeforeCaseColon: false +SpaceBeforeCpp11BracedList: false +SpaceBeforeCtorInitializerColon: true +SpaceBeforeInheritanceColon: true +SpaceBeforeParens: ControlStatements +SpaceBeforeParensOptions: + AfterControlStatements: true + AfterForeachMacros: true + AfterFunctionDefinitionName: false + AfterFunctionDeclarationName: false + AfterIfMacros: true + AfterOverloadedOperator: false + BeforeNonEmptyParentheses: false +SpaceBeforeRangeBasedForLoopColon: true +SpaceBeforeSquareBrackets: false +SpaceInEmptyBlock: false +SpaceInEmptyParentheses: false +SpacesBeforeTrailingComments: 2 +SpacesInAngles: Leave +SpacesInCStyleCastParentheses: false +SpacesInConditionalStatement: false +SpacesInContainerLiterals: false +SpacesInLineCommentPrefix: + Minimum: 0 + Maximum: -1 +SpacesInParentheses: false +SpacesInSquareBrackets: false +Standard: Auto +StatementAttributeLikeMacros: + - Q_EMIT +StatementMacros: + - Q_UNUSED + - QT_REQUIRE_VERSION +TabWidth: 2 +UseCRLF: false +UseTab: Never +WhitespaceSensitiveMacros: + - STRINGIZE + - PP_STRINGIZE + - BOOST_PP_STRINGIZE + - NS_SWIFT_NAME + - CF_SWIFT_NAME diff --git a/.codespellrc b/.codespellrc new file mode 100644 index 00000000000..690782793dd --- /dev/null +++ b/.codespellrc @@ -0,0 +1,9 @@ +[codespell] +# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/spell-check/.codespellrc +# In the event of a false positive, add the problematic word, in all lowercase, to a comma-separated list here: +ignore-words-list = ba,licence,ot,dout,als,exten,acount,totaly,pasttime +skip = ./.git,./.licenses,__pycache__,.clang-format,.codespellrc,.editorconfig,.flake8,.prettierignore,.yamllint.yml,.gitignore,boards.txt,platform.txt,programmers.txt +builtin = clear,informal,en-GB_to_en-US +check-filenames = +check-hidden = +write-changes = diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 00000000000..eda8544321b --- /dev/null +++ b/.editorconfig @@ -0,0 +1,60 @@ +# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/general/.editorconfig +# See: https://editorconfig.org/ +# The formatting style defined in this file is the official standardized style to be used in all Arduino Tooling +# projects and should not be modified. +# Note: indent style for each file type is defined even when it matches the universal config in order to make it clear +# that this type has an official style. + +[*] +charset = utf-8 +end_of_line = lf +indent_size = 2 +indent_style = space +insert_final_newline = true +trim_trailing_whitespace = true + +[*.{adoc,asc,asciidoc}] +indent_size = 2 +indent_style = space + +[*.{bash,sh}] +indent_size = 2 +indent_style = space + +[*.{c,cc,cp,cpp,cxx,h,hh,hpp,hxx,ii,inl,ino,ixx,pde,tpl,tpp,txx}] +indent_size = 2 +indent_style = space + +[*.{go,mod}] +indent_style = tab + +[*.java] +indent_size = 2 +indent_style = space + +[*.{js,jsx,json,jsonc,json5,ts,tsx}] +indent_size = 2 +indent_style = space + +[*.{md,mdx,mkdn,mdown,markdown}] +indent_size = unset +indent_style = space + +[*.proto] +indent_size = 2 +indent_style = space + +[*.py] +indent_size = 4 +indent_style = space + +[*.svg] +indent_size = 2 +indent_style = space + +[*.{yaml,yml}] +indent_size = 2 +indent_style = space + +[{.gitconfig,.gitmodules}] +indent_style = tab diff --git a/.flake8 b/.flake8 new file mode 100644 index 00000000000..efde3a0ccfb --- /dev/null +++ b/.flake8 @@ -0,0 +1,12 @@ +# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-python/.flake8 +# See: https://flake8.pycqa.org/en/latest/user/configuration.html +# The code style defined in this file is the official standardized style to be used in all Arduino tooling projects and +# should not be modified. + +[flake8] +doctests = True +# W503 and W504 are mutually exclusive. PEP 8 recommends line break before. +ignore = W503 +max-complexity = 10 +max-line-length = 120 +select = E,W,F,C,N diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml new file mode 100644 index 00000000000..67a4f012a7b --- /dev/null +++ b/.github/workflows/pre-commit.yml @@ -0,0 +1,26 @@ +name: Pre-commit check + +on: + pull_request: + types: [opened, reopened, synchronize, labeled] + +jobs: + lint: +# if: | +# contains(github.event.pull_request.labels.*.name, 'Status: Pending Merge') + name: Checking if any fixes are needed + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + - uses: actions/setup-python@v4 + with: + python-version: 3.8 + - id: changed-files + uses: tj-actions/changed-files@v36 + - uses: pre-commit/action@v3.0.0 + with: + extra_args: --files ${{ steps.changed-files.outputs.all_changed_files }} + - uses: pre-commit-ci/lite-action@v1.0.1 + if: always() diff --git a/.gitignore b/.gitignore index 2eea4128f55..67ae15c2bf9 100644 --- a/.gitignore +++ b/.gitignore @@ -21,7 +21,7 @@ tools/openocd-esp32 # Ignore build folder /build - + # Ignore files built by Visual Studio/Visual Micro [Dd]ebug/ [Rr]elease/ @@ -44,3 +44,9 @@ debug.cfg debug.svd debug_custom.json libraries/Insights/examples/*/*.ino.zip + +# Vale Style +.vale/styles/* +!.vale/styles/Vocab/ +.vale/styles/Vocab/* +!.vale/styles/Vocab/Espressif/ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 00000000000..d58c66750e6 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,64 @@ +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: "v4.5.0" + hooks: + - id: check-case-conflict + - id: check-symlinks + - id: debug-statements + - id: destroyed-symlinks + - id: detect-private-key + - id: end-of-file-fixer + - id: mixed-line-ending + args: [--fix=lf] + - id: trailing-whitespace + args: [--markdown-linebreak-ext=md] + - repo: https://github.com/codespell-project/codespell + rev: "v2.2.4" + hooks: + - id: codespell + exclude: ^.*\.(svd|SVD)$ + stages: [manual] + - repo: https://github.com/pre-commit/mirrors-clang-format + rev: "v15.0.7" + hooks: + - id: clang-format + types_or: [c, c++] + - repo: https://github.com/psf/black-pre-commit-mirror + rev: "22.10.0" + hooks: + - id: black + language_version: python3.8 + args: [--line-length=120] #From the arduino code style. Add as argument rather than creating a new config file. + - repo: https://github.com/PyCQA/flake8 + rev: "7.0.0" + hooks: + - id: flake8 + types_or: [python] + additional_dependencies: + - flake8-bugbear + - flake8-comprehensions + - flake8-simplify + - repo: https://github.com/pre-commit/mirrors-prettier + rev: "v3.1.0" + hooks: + - id: prettier + types_or: [yaml] + - repo: local + hooks: + - id: install-docutils + name: install-docutils + entry: pip install --upgrade docutils + language: system + pass_filenames: false + types_or: [markdown, rst] + - repo: https://github.com/errata-ai/vale + rev: "v3.0.7" + hooks: + - id: vale + name: vale-sync + language_version: "1.21.6" + pass_filenames: false + args: [sync] + - id: vale + language_version: "1.21.6" + types_or: [markdown, rst] diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 00000000000..58b8966740f --- /dev/null +++ b/.prettierignore @@ -0,0 +1,4 @@ +__pycache__/ +.clang-format +.licenses/ +/.git/ diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 00000000000..d51d3016a57 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,118 @@ +################### +### Vale Config ### +################### + +# This is a Vale linter configuration file. +# - Repo: arduino-esp32 +# - Based on Default config: v0-1-1 +# It lists all necessary parameters to configure Vale for your project. +# For official documentation on all config settings, see +# https://vale.sh/docs/topics/config + + +############## +### Global ### +############## + +# This section lists core settings applying to Vale itself. + + +# Specify path to external resources (e.g., styles and vocab files). +# The path value may be absolute or relative to this configuration file. +StylesPath = .vale/styles + + +# Specify the minimum alert severity that Vale will report. +MinAlertLevel = suggestion # "suggestion", "warning", or "error" + + +# Specify vocabulary for special treatment. +# Create a folder in /Vocab//and add its name here +# The folder should contain two files: +# - accept.txt -- lists words with accepted case-sensitive spelling +# - reject.txt -- lists words whose occurrences throw an error +# Vocab = Espressif + + +# Specify the packages to import into your project. +# A package is a zip file containing a number of rules (style) written in YAML. +# For a list of official packages, see Package Hub at https://vale.sh/hub/ +# For official documentation on packages, see +# https://vale.sh/docs/topics/packages/ +# Before linting, navigate to your project and run `vale sync` to download +# the official packages specified below. +# Packages = Package1, Package2, \ +# https://example.com/path/to/package/Package.zip +Packages = Google, Microsoft, RedHat, \ +https://dl.espressif.com/dl/esp-vale-config/Espressif-latest.zip + + +############### +### Formats ### +############### + +# This section enables association of "unknown" formats with the ones +# supported by Vale. For official documentation on supported formats, see +# https://vale.sh/docs/topics/scoping/ +[formats] + +# For example, treat MDX files as Markdown files. +# mdx = md + + +################################ +### Format-specific settings ### +################################ + +# This section lists the settings that apply to specific file formats +# based on their glob pattern. +# Settings provided under a more specific glob pattern, +# such as [*.{md,txt}] will override those in [*]. +[*.{md,rst}] + + +# Enable styles to activate all rules included in them. +# BasedOnStyles = Style1, Style2 +BasedOnStyles = Vale, Espressif-latest + + +### Deactivate individual rules ### +### in enabled styles. +# Style1.Rule1 = NO +Vale.Repetition = NO +Vale.Spelling = NO +Espressif-latest.Admonitions = NO +Espressif-latest.Contractions = NO +Espressif-latest.Monospace = NO + + +### Change default severity level ### +### of an activated rule. +# Choose between "suggestion", "warning", or "error". +# Style1.Rule2 = error + + +### Activate individual rules ### +### in non-enabled styles stored in . +# Style1.Rule = YES +Google.Gender = YES +Google.GenderBias = YES +Google.Slang = YES +Google.Spacing = YES +Microsoft.DateNumbers = YES +Microsoft.Ellipses = YES +Microsoft.FirstPerson = YES +Microsoft.Hyphens = YES +Microsoft.Ordinal = YES +Microsoft.OxfordComma = YES +Microsoft.Percentages = YES +Microsoft.RangeTime = YES +Microsoft.Semicolon = YES +Microsoft.SentenceLength = YES +Microsoft.Suspended = YES +Microsoft.Units = YES +Microsoft.URLFormat = YES +Microsoft.We = YES +Microsoft.Wordiness = YES +RedHat.Contractions = YES +RedHat.RepeatedWords = YES diff --git a/docs/en/dummy.rst b/docs/en/dummy.rst new file mode 100644 index 00000000000..9267f1b427f --- /dev/null +++ b/docs/en/dummy.rst @@ -0,0 +1,155 @@ +############### +Getting Started +############### + +About Arduino ESP32 +------------------- + +Welcome to the Arduino ESP32 support documentation! Here you will find important information on how to use the project. + +First Things First +------------------ + +.. note:: + Before continuing, we must be clear that this project is supported by `Espressif Systems`_ and the community. + Everyone is more than welcome to contribute back to this project. + +ESP32 is a single 2.4 GHz Wi-Fi-and-Bluetooth SoC (System On a Chip) designed by `Espressif Systems`_. + +ESP32 is designed for mobile, wearable electronics, and Internet-of-Things (IoT) applications. It features all the state-of-the-art characteristics +of low-power chips, including fine-grained clock gating, multiple power modes,and dynamic power scaling. For instance, in a low-power IoT sensor +hub application scenario, ESP32 is woken-up periodically and only when a specified condition is detected. Low-duty cycle is used to minimize the +amount of energy that the chip expends. + +The output of the power amplifier is also adjustable, thus contributing to an optimal trade-off between communication range, data rate and +power consumption. + +The ESP32 series is available as a chip or module. + + +.. _supported_socs: + +Supported SoC's +--------------- + +Here are the ESP32 series supported by the Arduino-ESP32 project: + +======== ====== =========== =================================== +SoC Stable Development Datasheet +======== ====== =========== =================================== +ESP32 Yes Yes `ESP32`_ +ESP32-S2 Yes Yes `ESP32-S2`_ +ESP32-C3 Yes Yes `ESP32-C3`_ +ESP32-S3 Yes Yes `ESP32-S3`_ +ESP32-C6 No Yes `ESP32-C6`_ +ESP32-H2 No Yes `ESP32-H2`_ +======== ====== =========== =================================== + +See `Boards `_ for more details about ESP32 development boards. + +Arduino Core Reference +---------------------- + +This documentation is built on the ESP32 and we are not going to cover the common Arduino API. To see the Arduino reference documentation, +please consider reading the official documentation. + +Arduino Official Documentation: `Arduino Reference`_. + +Supported Operating Systems +--------------------------- + ++-------------------+-------------------+-------------------+ +| |windows-logo| | |linux-logo| | |macos-logo| | ++-------------------+-------------------+-------------------+ +| Windows | Linux | macOS | ++-------------------+-------------------+-------------------+ + +.. |windows-logo| image:: ../_static/logo_windows.png +.. |linux-logo| image:: ../_static/logo_linux.png +.. |macos-logo| image:: ../_static/logo_macos.png + +Supported IDEs +--------------------------- + +Here is the list of supported IDE for Arduino ESP32 support integration. + ++-------------------+-------------------+ +| |arduino-logo| | |pio-logo| | ++-------------------+-------------------+ +| Arduino IDE | PlatformIO | ++-------------------+-------------------+ + +.. |arduino-logo| image:: ../_static/logo_arduino.png +.. |pio-logo| image:: ../_static/logo_pio.png + +See `Installing Guides `_ for more details on how to install the Arduino ESP32 support. + +Support +------- + +This is an open project and it's supported by the community. Fell free to ask for help in one of the community channels. + +Community +--------- + +The Arduino community is huge! You can find a lot of useful content on the Internet. +Here are some community channels where you may find information and ask for some help, if needed. + +- `ESP32 Forum`_: Official Espressif Forum. +- `ESP32 Forum - Arduino`_: Official Espressif Forum for Arduino related discussions. +- `ESP32 Forum - Hardware`_: Official Espressif Forum for Hardware related discussions. +- `Gitter`_ +- `Espressif MCUs (Discord)`_ +- `ESP32 on Reddit`_ + +Issues Reporting +---------------- + +Before opening a new issue, please read this: + +Be sure to search for a similar reported issue. This avoids duplicating or creating noise in the GitHub Issues reporting. +We also have the troubleshooting guide to save your time on the most common issues reported by users. + +For more details about creating new Issue, see the `Issue Template `_. + +If you have any new idea, see the `Feature request Template `_. + +First Steps +----------- + +Here are the first steps to get the Arduino ESP32 support running. + +To install Arduino-ESP32, please see the dedicated section on the Installation guide. We recommend you install it using the boards manager. + +.. toctree:: + :maxdepth: 2 + + How to Install + Development Boards + +Examples +-------- + +After installing the toolchain into your environment, you will be able to see all the dedicated examples for the ESP32. These examples are located +in the examples menu or inside each library folder. + + https://github.com/espressif/arduino-esp32/tree/master/libraries + +There is also a `list of examples `_ managed outside of Espressif, so check them out. + +.. include:: common/datasheet.inc + +Resources +--------- + +.. _Espressif Systems: https://www.espressif.com +.. _Espressif Product Selector: https://products.espressif.com/ +.. _Arduino.cc: https://www.arduino.cc/en/Main/Software +.. _Arduino Reference: https://www.arduino.cc/reference/en/ +.. _ESP32 Forum: https://esp32.com +.. _ESP32 Forum - Arduino: https://esp32.com/viewforum.php?f=19 +.. _ESP32 Forum - Hardware: https://esp32.com/viewforum.php?f=12 +.. _Gitter: https://gitter.im/espressif/arduino-esp32 +.. _Adafruit (Discord): https://discord.gg/adafruit +.. _Espressif MCUs (Discord): https://discord.gg/nKxMTnkD +.. _ESP32 on Reddit: https://www.reddit.com/r/esp32