Mercurial > iotbalkon / changeset

--- a/CMakeLists.txt	Sun Mar 26 22:22:45 2023 +0200
+++ b/CMakeLists.txt	Mon Mar 27 22:13:21 2023 +0200
@@ -4,5 +4,9 @@
 # CMakeLists in this exact order for cmake to work correctly
 cmake_minimum_required(VERSION 3.16)
 
+set(PROJECT_VER "0.0.1")
+set(PROJECT_NAME "iotbalkon")
+
+set(EXTRA_COMPONENT_DIRS esp-idf-lib/components)
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 project(iotbalkon)

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/esp-idf-lib/CHANGELOG.md	Mon Mar 27 22:13:21 2023 +0200
@@ -0,0 +1,248 @@
+# Changelog
+
+## v.0.9.2
+
+### Features
+- (ds3231): Added ds3231_get_squarewave_freq by @dizcza in https://github.com/UncleRus/esp-idf-lib/pull/447
+- (ads130e08): Driver for ADS130E08 ADC by @weslleymfd in https://github.com/UncleRus/esp-idf-lib/pull/462
+- (dps310): DPS310 driver by @trombik in https://github.com/UncleRus/esp-idf-lib/pull/463
+
+### Bugfixes
+- (pca9557): Fixed incorrect I2C address and register bug by @AxelLin in https://github.com/UncleRus/esp-idf-lib/pull/453
+- (max7219) Fix string bounds check by @UncleRus in https://github.com/UncleRus/esp-idf-lib/pull/471
+- (ci) Updated esp-idf versions by @trombik
+- (ci) Updated actions/checkout to v3 by @trombik in https://github.com/UncleRus/esp-idf-lib/pull/476
+- (esp_idf_lib_helpers): Fixed ets_sys.h error by @UncleRus in https://github.com/UncleRus/esp-idf-lib/pull/479
+- (i2cdev): Fixed i2c param config and driver install order for esp32 target by @AxelLin in https://github.com/UncleRus/esp-idf-lib/pull/475
+
+## New Contributors
+* @AxelLin made their first contribution in https://github.com/UncleRus/esp-idf-lib/pull/453
+* @weslleymfd made their first contribution in https://github.com/UncleRus/esp-idf-lib/pull/462
+
+### Documentation: https://esp-idf-lib.readthedocs.io/en/0.9.2/
+
+## v.0.9.1
+
+### Features
+- (lc709203f): Driver for LC709203F battery fuel gauge by @jmpmscorp in https://github.com/UncleRus/esp-idf-lib/pull/433
+- (hmc5883l): Added support for HMC5983 by @dizcza in https://github.com/UncleRus/esp-idf-lib/pull/431
+
+### Bugfixes
+- (i2cdev): Fixed I2C driver reinstallation bug by @UncleRus in https://github.com/UncleRus/esp-idf-lib/pull/430
+- (chore): Updated io-console by @trombik in https://github.com/UncleRus/esp-idf-lib/pull/435
+- (doc): Reordered Usages of metadata in the project section by @trombik in https://github.com/UncleRus/esp-idf-lib/pull/439
+- (all): Fixed xprintf() format specifications in components and examples to support ESP-IDF v5 by @UncleRus
+- (ci): Fixed generation of components list by @UncleRus in https://github.com/UncleRus/esp-idf-lib/pull/446
+
+## New Contributors
+- @jmpmscorp made their first contribution in https://github.com/UncleRus/esp-idf-lib/pull/433
+
+### Documentation: https://esp-idf-lib.readthedocs.io/en/0.9.1/
+
+
+## v.0.9.0
+
+### Features
+- (docs) How to porting i2c libs by @dizcza in https://github.com/UncleRus/esp-idf-lib/pull/428
+- (sts21) Driver for STS21 temperature sensor by @UncleRus in https://github.com/UncleRus/esp-idf-lib/pull/326
+- (max31855) Driver for MAX31855 cold-junction compensated thermocouple-to-digital converter by @UncleRus in https://github.com/UncleRus/esp-idf-lib/pull/324
+- (ht16k33) Driver for HT16K33 LED driver by @chudsaviet in https://github.com/UncleRus/esp-idf-lib/pull/341
+- (ci) All-new awesome label-based workflow with auto-labeler by @trombik
+- (ci) Introduced release-drafter GitHub Actions workflow by @trombik in https://github.com/UncleRus/esp-idf-lib/pull/338
+- (chore) Added clang-format options file by @UncleRus in https://github.com/UncleRus/esp-idf-lib/pull/421
+- (tca9548): Added example by @UncleRus in https://github.com/UncleRus/esp-idf-lib/pull/424
+
+### Bugfixes
+- (all) Fixed requirements in components using `esp_timer` by @EldritchJS in https://github.com/UncleRus/esp-idf-lib/pull/328
+- (lm75, pca9557) Fixed type casting warnings by @UncleRus in https://github.com/UncleRus/esp-idf-lib/pull/400
+- (ads111x) Fixed bug `in ads111x_is_busy()` (#418) by @UncleRus in https://github.com/UncleRus/esp-idf-lib/pull/419
+
+## New Contributors
+- @EldritchJS made their first contribution in https://github.com/UncleRus/esp-idf-lib/pull/328
+- @chudsaviet made their first contribution in https://github.com/UncleRus/esp-idf-lib/pull/341
+
+### Documentation: https://esp-idf-lib.readthedocs.io/en/0.9.0/
+
+
+## v.0.8.3
+
+### Changes that break compatibility 
+- ⚠ (bh1900nux, max31725, mcp23008, mcp23x17, mcp342x, mcp4725, pca9557, pcf8574, pcf8575, qmc5883l, sht3x, tca9548, tca95x5): The order of the arguments in `xxx_init_desc()` functions has been changed to bring all drivers to a common standard: instead of `xxx_init_desc(..., i2c_port_t port, uint8_t addr, ...)`, now `xxx_init_desc(..., uint8_t addr, i2c_port_t port, ...)`. Attention: both arguments are ints, so compiler will not throw an error when building your firmware without changing it!
+- (common) Dropped support for ESP-IDF v3.x
+
+### Features
+- (common) Added support for ESP32-C3
+- (hts221) Driver for HTS221 temperature and humidity sensor
+- (hdc1000) Driver for HDC1000 temperature and humidity sensor
+- (examples) Constant parameters in examples have been moved to Kconfig.projbuild files, so you can now setup examples by `idf.py menuconfig` or `make menuconfig` instead of modifying source code.
+- (examples) Added README to all examples
+- (hx711) Added function to read average data
+- (bh1900nux) Added software reset function
+- (ds3231) Added functions to set and get aging offset register
+- (esp_idf_lib_helper): Moved ets_sys.h includes to the separate file
+
+### Bugfixes
+- (i2cdev) Showing error name in error logging
+- (color) Fixed narrowing conversion error
+- (examples) Use SPI2_HOST in examples with ESP-IDF v4.x
+- (rda5807) Replaced `ESP_LOGI()` to `ESP_LOGD()`
+- (led_strip_spi) Fixed pointer arithmetic for esp8266
+- (led_strip_spi) Fixed "initialized field overwritten" warning
+- (mcp960x) Fixed incorrect I2C addressing
+
+### Documentation: https://esp-idf-lib.readthedocs.io/en/0.8.3/
+
+## v.0.8.2
+
+### Features
+- (max31865) Driver for MAX31865 resistance converter for platinum RTDs
+- (pca9557) Driver for PCA9537/PCA9557 remote 4/8-bit I/O expanders for I2C-bus
+- (ls7366r) Driver for LS7366R Quadrature Encoder Counter
+- (ci) Added metadata support
+- (bh1900nux) Driver for BH1900NUX temperature sensor
+
+### Bugfixes
+- (scd30) Fixed type casting warning
+- (ccs811) Fixed claculation bug in ccs811_set_environmental_data()
+- (max7219) Fixed bug with chip number in 8x8 example
+- (button) Added user context do descriptor
+- (si7021) Fixed delay for SHT20
+- (led_strip_spi) Added brightness support
+- (pcf8563) Fixed mdays/wdays bug
+- (sht4x) Fixed bug in example
+- (led_strip) Fixed memory leak when handling error in led_strip_init()
+
+
+## v.0.8.1
+
+### Features
+- (button) Driver for GPIO button with debouncing
+- (scd30) Driver for SCD30 CO₂ sensor
+- (scd4x) Driver for SCD40/SCD41 miniature CO₂ sensor
+- (aht) Driver for AHT10/AHT15/AHT20 temperature and humidity sensor
+
+### Bugfixes
+- (mzh19b) Fixed bug with serial buffer length used by the driver
+- (framebuffer) Used a mutex instead of flag, fixed "maybe-uninitialized"
+- (sgp40) Multiple bugs fixed
+- (sht4x) Added 10ms timout for reading serial number
+- (rda5807m) Default I2C clock lowered, example added
+- (color) Fix build with c++
+- (examples) Fixed build of examples for single core ESP32s (S2/C3)
+- (ds18x20) Added split 18B20/18S20 reads to allow for use of DS18X20_ANY
+  without flubbing the conversion on an 18B20
+- (ds18x20) Added scratchpad write and copy commands
+
+
+## v.0.8.0
+
+### Features
+- (wiegand) Wiegand protocol receiver
+- (lib8tion) Math functions specifically designed for LED programming (port
+  from FastLED)
+- (color) Common library for RGB and HSV colors (port from FastLED)
+- (noise) Noise generation functions (port from FastLED)
+- (framebuffer) RGB framebuffer and animation component
+- (mhz19b) Added support for the MH-Z19B CO2 sensor
+- (ci) Dropped support for ESP-IDF < v3.5
+- (ci) Preliminary and untested support for ESP32-C3
+- (ci) Support ESP8266 RTOS SDK v3.3
+- (doc) Added initial version of CONTRIBUTING.md
+
+### Bugfixes
+- (sht3x) Fixed documentation
+- (ds18x20) Fixed ds18x20_scan_devices(), new example
+- (ultrasonic) Added more precise measurement functions
+- (led_strip_spi) Fixed SPI buffer limitation for ESP8266
+- (led_strip) Fixed buffer overflow error for RGBW strips
+- (led_strip) White component for RGBW strips now calculated automatically
+- (led_strip) Fixed bug in led_strip_set_pixels()
+- (led_strip) Added support for global brightness for ESP-IDF >= v4.4
+- (led_strip) Improved stability for WS2812B
+- (refactoring) Updated component makefiles and CMakeLists
+- (i2cdev) Added option to disable all mutexes
+
+
+## v.0.7.3
+
+### Features
+- (led_strip_spi) #156 SPI-based driver for SK9822/APA102 LED strips
+- (ds3502) #160 Driver for nonvolatile digital potentiometer DS3502
+- (sht4x) #165 Driver for SHT4x temperature and humidity sensor
+
+### Bugfixes
+- (pca9685) b633f86 Speed-ups
+- (max7219) #159 Add "minus" sign and fix maximum brightness
+
+
+## v.0.7.2
+
+### Features
+- (tsl2591) #149 Driver for light-to-digital converter TSL2591
+- (sgp40) #137 Driver for SGP40 Indoor Air Quality Sensor
+- (ccs811) #67 Driver for AMS CCS811 digital gas sensor
+
+### Bugfixes
+- (ci) #147 Cache Espressif tools
+- (ci) #155 Update v4.2 branch
+- (led_strip) #153 Tweak led_strip example, add README
+- (led_strip) #154 Fix range bug in led_strip_fill
+- (sht3x, ...) #151 Typo corrections + SHT3x corrections and improvement
+- (sht3x) #152 Fix periodic measurement
+- (hx711) a2b9fc5 Fix incorrect spinlock usage
+- (doc) Multiple fixes
+- (pca9685) ce8f3fa Fix possible race condition
+
+
+## v.0.7.1
+
+### Features
+- (mcp960x) #141 Driver + example for MCP960X/L0X/RL0X
+- (tsys01) #142 Driver + example for TSYS01
+
+### Bugfixes
+- (qmc5883l) dd17522 Fix possible race condition
+- (tca95x5) #144 Copy-paste error, add example
+- (esp_idf_lib_helpers) #143 Invalid error message
+- (tsl4531) c2e835d Fix possible race condition
+- (sht3x) 8289262 Fix possible race confition in SS measurement, refactoring
+- (bh1750, bmp180) d57488b Fix possible race condition
+
+
+## v.0.7
+
+### Features
+- (ina260) #126 Driver for INA260 precision digital current and power monitor
+- (rda5807m) #25 Driver for single-chip broadcast FM radio tuner RDA5807M
+- (i2cdev) #138 I2C clock stertching support
+
+
+## v.0.6.1
+
+### Bugfixes
+- (ina219) #100 Potential error in ina219_get_gain
+- (bme680) #121 Pressure calculation for bme680 gives wrong results
+
+
+## v.0.6
+
+### Features
+- (ci) #116 Port CI process from Travis CI to GitHub Actions
+- (ci) Update CI build tools
+- (ads111x) #117 Support of ADS101x on top ADS111x
+- (led_strip) #120 Smart LED strips support
+
+### Bugfixes
+- (ds1307) #110 wrong squarewave frequency returned
+- (sht3x, hmc5883l, hx711) #118 SHT3x measurements fail after 72min
+- (pca9685) d4f5e35 Fix full on/off
+- (ina219) Typo fix
+
+
+## v.0.5-beta
+
+### Features
+- (mcp342x) #92 Driver for ADC MCP3426/MCP3427/MCP3428
+
+### Bugfixes
+- (ds1302) #97 Fix critical section exit

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/esp-idf-lib/CONTRIBUTING.md	Mon Mar 27 22:13:21 2023 +0200
@@ -0,0 +1,617 @@
+# How to contribute to `esp-idf-lib`
+
+## Table of Contents
+
+<!-- vim-markdown-toc GFM -->
+
+* [Possible contributions](#possible-contributions)
+    * [Submitting a bug report](#submitting-a-bug-report)
+    * [Submitting a fix](#submitting-a-fix)
+    * [Writing documentation](#writing-documentation)
+    * [Suggesting enhancements](#suggesting-enhancements)
+    * [Promoting the project](#promoting-the-project)
+    * [Writing code](#writing-code)
+* [Development Life Cycle](#development-life-cycle)
+    * [Creating an Issue](#creating-an-issue)
+    * [Creating a feature branch in your fork and develop](#creating-a-feature-branch-in-your-fork-and-develop)
+    * [C Code style](#c-code-style)
+    * [`markdown` Code style](#markdown-code-style)
+    * [`git` branch name convention](#git-branch-name-convention)
+    * [Typical issues you will face in developments](#typical-issues-you-will-face-in-developments)
+    * [Writing a commit message](#writing-a-commit-message)
+    * [Updating README.md](#updating-readmemd)
+    * [Creating a Pull Request](#creating-a-pull-request)
+* [Licenses](#licenses)
+    * [Acceptable licenses](#acceptable-licenses)
+    * [Acceptable license for new code](#acceptable-license-for-new-code)
+    * [Unacceptable licenses](#unacceptable-licenses)
+
+<!-- vim-markdown-toc -->
+
+## Possible contributions
+
+If you would like to contribute to `esp-idf-lib`, we would like to say _thank
+you_. We appreciate your efforts and contributions. Here is possible
+contributions you can make.
+
+* [Submitting a bug report](#submitting-a-bug-report)
+* [Submitting a fix](#submitting-a-fix)
+* [Writing documentation](#writing-documentation)
+* [Suggesting enhancements](#suggesting-enhancements)
+* [Promoting the project](#promoting-the-project)
+* [Writing code](#writing-code)
+
+### Submitting a bug report
+
+In embedded device development, finding bugs is more difficult than in other
+software development. There are too many uncontrollable factors: physical
+environment, counterfeit IC chips, deviations in revisions and variations,
+difficulties in automations. Even if the bug turned out to be not a bug, such
+report is still appreciated as it is another proof that the code works as
+expected in a different environment.
+
+Please include how to reproduce the bug in the Issue. The more context, the
+better. For example:
+
+* The _full_ error message in text format and the entire code (comment with
+  ` ``` ` for short code, use [Gist](https://gist.github.com) for long code)
+* The circuit diagram
+* Captured signals by an oscilloscope or a signal analyser ([sigrok](https://sigrok.org/))
+
+A question as a bug report is okay but we expect bug reporters to do their
+homework. The homework include:
+
+* Reading the data sheets
+* Reading [the official documentation of `esp-idf`](https://docs.espressif.com/projects/esp-idf)
+  (it's good, really)
+* Understanding C language in general
+
+For introductory C tutorials, see:
+
+* [C Tutorial](https://www.tutorialspoint.com/cprogramming/) by
+  `Tutorialspoint`
+* [C Programming](https://en.wikibooks.org/wiki/C_Programming) by
+  `Wikibooks`
+
+### Submitting a fix
+
+If you found a bug and a fix for it, please create a bug report before
+creating a Pull Request unless the bug is subtle, typos, or easy to reproduce
+and fix. Make sure to read [Development Life Cycle](#development-life-cycle)
+as a Pull Request must meet the same standards documented in the section.
+
+A GitHub Actions workflow,
+[pr-labeler-action](https://github.com/TimonVS/pr-labeler-action), is used to
+label PRs by branch name. Your fix branch should have prefixes defined in
+[.github/pr-labeler.yml](.github/pr-labeler.yml). Create a branch with one of
+the prefixes. If you are fixing a bug, your branch name should be `bugfix-`.
+The rest of branch name should be short, and descriptive. If the fix has
+related issues, the branch name should include them.
+
+See also [`git` branch name convention](#git-branch-name-convention).
+
+```console
+git checkout -b bugfix-issue-1
+```
+
+Change the branch name before creating a PR if your branch name does not
+follow the convention.
+
+```console
+git branch --move bugfix-issue-1
+```
+
+### Writing documentation
+
+Even if you are not an author of the code in the repository, you can write
+documentation as a contribution.
+
+Creating and maintaining FAQ entries is one of great examples. Have you
+encountered seemingly common issues while using a component? That might help
+others.
+
+We encourage code authors to write documentation in the code so that the code
+and the documentation is always synced. However, sometimes they are not.
+Spotting such mistakes is always appreciated.
+
+Not all contributors are native English speakers. If you are, please let us
+know ambiguity in the documentation, wrong usages of terms, and mistakes in
+English grammar. For this case, please create a Pull Request (creating an
+issue is optional).
+
+Create a branch that documents features, or fixes existing documentations.
+
+```console
+git checkout -b doc-foo
+```
+
+See also [`git` branch name convention](#git-branch-name-convention).
+
+### Suggesting enhancements
+
+While we are not always able to write a driver for a chip, we still appreciate
+a request for new driver. It is more likely to happen when:
+
+* the chip is _cool_
+* the chip is easily available
+* the chip is affordable
+
+### Promoting the project
+
+If you find the project useful, we are interested in what you did with
+`esp-idf-lib`, and _how_ you did it.
+
+* Writing a blog post about your porject with `esp-idf-lib`
+* Mentioning the project in SNS
+
+### Writing code
+
+If you can write a driver for new chip, that would be great. Please read
+[Development Life Cycle](#development-life-cycle).
+
+## Development Life Cycle
+
+In this section, a typical development life cycle is explained.
+
+### Creating an Issue
+
+If you are working on a new driver, or an existing one, please create an
+Issue, and assign the Issue to yourself.
+
+`esp-idf-lib` aims at providing stable drivers for IC chips and general
+components. IC chips are stable, in that a chip is manufactured for a long
+time, retaining backward compatibilities. A driver for a chip usually requires
+minimal maintenance once the driver becomes stable. However, network protocols,
+graphics drivers, libraries for external services, are a moving-target.
+Standards will change, external services will evolve, user expectations will
+change, too. We think that such moving-targets should be maintained in a
+dedicated repository. Do you think your code is a moving target? It might be
+better to create a your own repository for the driver. If you are not sure,
+ask in the Issue.
+
+### Creating a feature branch in your fork and develop
+
+_Feature branch workflow_ is adopted in our development.
+[Git Feature Branch Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow)
+by `atlassian` explains the workflow in details.
+
+Fork the repository and clone it on your machine.
+See [Fork a repo](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo).
+
+Create a feature branch in your fork from the `master` branch.
+
+```console
+git checkout master
+```
+
+Check out the feature branch. The feature branch name should start with
+`feat-` or `feature-`.
+
+```console
+git checkout -b feat-implement-foo
+````
+
+See also [`git` branch name convention](#git-branch-name-convention).
+
+Write your code. Test the code in your physical test environment.  Commit your
+changes and push them to your remote fork on GitHub.
+
+[`components/example`](components/example) has an example component, and
+[`examples/example`](examples/example) has an example application for the
+`example` component.
+
+```console
+git add path/to/files
+git commit -v
+git push --set-upstream origin feat-implement-foo
+````
+
+See also [Writing a commit message](#writing-a-commit-message).
+
+At this point, our CI workflows will run to test the changes. The test
+workflows include:
+
+* building the documentation,
+* building all examples for all supported targets with all supported
+  `esp-idf` versions, and
+* linting code and documentation
+
+You can see the test results in `Actions` page on your GitHub fork. To
+merge your changes to `master` branch, all the tests must pass.
+
+Make sure you are working on the latest `master` of `esp-idf-lib`. To sync the
+`master` in your fork and the latest `master` of `esp-idf-lib`, run:
+
+```console
+git checkout master
+git fetch upstream
+git reset --hard upstream/master
+```
+
+If your branch has many commits, consider `git rebase` to reduce the number of
+commits. This is especially useful when you are actively developing and the
+commit history has many trial-and-error commits.
+
+```console
+git checkout feat-implement-foo
+git rebase -i master
+git push -f
+```
+
+Note that `git rebase` rewrites the commit history. You should avoid `git
+rebase` after you asked someone to review your code because the reviewer needs
+additional steps to ensure the review result is included.
+
+### C Code style
+
+We use a style for source files based on [LLVM Coding Standards](https://llvm.org/docs/CodingStandards.html)
+except some cases, notably brace wrapping. Here is a brief list of the styles.
+
+* Use `snake_case`, not `CamelCase`
+* Use `SNAKE_CASE` in uppercase for macro name, e.g. `MACRO_NAME`.
+* Use spaces. The indent width is four
+* Use `\n`, or `LF` for line breaks
+* Use `//` for inline comments. Use `/* */` for multi line comments after an
+  empty line
+* Break before braces in *most cases* (functions, conditionals, control
+  statements, etc)
+* Always check given arguments
+* Always check return code, return value, or `errno`
+* Return `esp_err_t` from functions where possible
+* Document public functions, data types, and macros in header files
+* Use suffix `_t` for `typedef`, e.g. `foo_t`
+* Use suffix `_cb_t` for function `typedef`, e.g.`my_function_cb_t`
+* Use suffix `_s` for `struct`, e.g. `my_struct_s`
+* Wrap numbers in macro definition with parenthesis, e.g. `#define N_FOO (1)`
+* Use `#include <foo.h> for headers that are not part of the component, such
+  as `string.h`, `esp_log,h`, and `i2cdev.h`. Use `#include "foo.h" when the
+  header is private, i.e. the header is the part of the component.
+
+The style should be followed for all new code. In general, code can be
+considered "new code" when it makes up about 50% or more of the file(s)
+involved. This is enough to break precedents in the existing code and use the
+current style guidelines.
+
+See an example source files under [`components/exmaple`](components/example)
+and, for complete rules, see [`.clang-format`](.clang-format) and the output
+of `clang-format --dump-config`.
+
+New code will be tested in the CI, using `clang-format` (currently `LLVM`
+version 10).
+
+To format your code without modifying the code, run:
+
+```console
+clang-format10 components/example/example.c
+```
+
+To format your code in-place, run:
+
+```console
+clang-format10 -i components/example/example.c
+```
+
+### `markdown` Code style
+
+We use [the default `markdownlint` rules](https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md)
+with some non-defaults. Our style can be found in [`.mdlstyle.rb`](.mdlstyle.rb).
+
+| Rule                                 | non-default options                            |
+| ------------------------------------ | ---------------------------------------------- |
+| `MD003` - Header style               | use `#` for headers                            |
+| `MD007` - Unordered list indentation | indent with 4 spaces                           |
+| `MD013` - Line length                | ignore line length in code blocks and tables   |
+| `MD024` - Multiple headers with the same content | `allow_different_nesting` is true  |
+| `MD029` - Ordered list item prefix   | `style` is `ordered`, i.e. incremental numbers |
+
+In the CI, we use ruby version of `markdownlint`, or [`mdl`](https://rubygems.org/gems/mdl/)
+gem, but [markdownlint for node.js](https://github.com/DavidAnson/markdownlint)
+should also work.
+
+To test `markdown` style of a file, you need:
+
+* `ruby` 2.6
+* `bundler` 2.x
+
+```console
+bundle install
+bundle exec mdl path/to/file
+```
+
+The output shows path to the file, line number, and the rule.  An example
+output is shown below.
+
+```console
+examples/led_strip_spi/README.md:30: MD040 Fenced code blocks should have a language specified
+```
+
+### `git` branch name convention
+
+We use the following convention for git branch name. Use one of branch name
+prefixes when creating a branch.
+
+| Branch name prefix | Description |
+|--------------------|-------------|
+| `feat-`, and `feature-` | A feature branch that implements feature(s), or add enhancement(s) to existing code |
+| `fix-`, and `bugfix-` | A bug fix branch that fixes bug(s). The rest of the branch name should include issue number, such as `fix-issue-1` |
+| `ci-` | A branch that implements enhancement(s), or fixes issue(s) in CI |
+| `chore-` | A branch that does not affect code or its behavior, such as updating `.gitignore` |
+| `doc-`, and `documentation-` | Adding or updating documentation only, such as documenting undocumented features, or fixing existing documentation(s) |
+
+A GitHub Actions workflow automatically labels PRs depending on the branch
+name prefixes so that the PR is automatically included in release notes.
+
+The rest of the branch name should be short, and descriptive. If your branch
+fixes, implements, or relates to, an Issue, include the Issue number. Say, if
+your branch fixes a bug reported Issue ${N}, the branch name should be
+`fix-issue-${N}` so that reviewer immediately understand there is a related
+Issue with your branch. Replace `${N}` with the Issue number, such as
+`fix-issue-123` when the Issue number is 123.
+
+### Typical issues you will face in developments
+
+**Your code assumes a single target, such as `esp32`**. `esp-idf-lib` supports
+other targets, notably `esp8266`. Make sure the driver supports various other
+targets. If it cannot, such as the peripheral is not available on the target
+chip, your code should bailout during the build by using `#error` C
+preprocessor macro, and your driver must be excluded from the CI (TODO
+document how).
+
+**Your code assumes a single SDK**. `esp-idf-lib` supports `master` and stable
+versions of `esp-idf` and `ESP8266 RTOS SDK`. Generally, the SDKs retain
+backward compatibilities, but sometimes not. Make sure to use `if` C
+preprocessor macro to support different versions. [`esp_idf_lib_helpers`](components/esp_idf_lib_helpers)
+component can help you. `ESP8266 RTOS SDK` shares many functions and
+libraries, backported from `esp-idf`, but they are not identical. `I2C`
+drivers written with [`i2cdev`](components/i2cdev) should work fine on ESP32
+and ESP8266, while SPI drivers need serious workarounds to support ESP8266.
+[`led_strip_spi`](components/led_strip_spi) attempted to support both, but you
+might want to write a different driver for each.
+
+**Your code assumes a single build method, such as `idf.py`**. Although `GNU make`
+build method is considered as legacy, it is still a supported build method.
+The CI builds your code twice; with `idf.py` and with `GNU make`. Both must be
+successful. In ESP8266 RTOS SDK, `idf.py` is lagged behind from the one in
+`esp-idf`. For ESP8266 target, the CI builds examples with `GNU make` only.
+
+Check return codes (most of functions in `esp-idf`), return values (e.g.
+`malloc(3)`), or `errno` (e.g. some standard C functions).  Propagate the
+error by returning it from your function. An example:
+
+```c
+#include <esp_err.h>
+#include <esp_log.h>
+
+esp_err_t do_something()
+{
+    esp_err_t err;
+
+    err = foo();
+    if (err != ESP_OK)
+    {
+        ESP_LOGE("bar", "foo(): %s", esp_err_to_name(err));
+        goto fail;
+    }
+fail:
+    return err;
+}
+```
+
+Note that newer `esp-idf` supports useful macros for error handling, such as
+`ESP_GOTO_ON_ERROR` (see
+[Error Handling](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/error-handling.html)),
+but older versions do not have them yet.
+
+Check given arguments in functions, and return an appropriate error from one
+of predefined errors (see
+[Error Codes Reference](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/error-codes.html)).
+
+### Writing a commit message
+
+When you commit, prefix the first line of your commit message with `foo:`,
+where `foo` is the name of component you are working on. Sometimes, it is not
+possible because you are working on multiple components, i.e. fixing common
+bugs in multiple components. In such cases, use `bugfix:`. Other commonly used
+prefix words are:
+
+* `feature:` for features, or improvements, in multiple components
+* `ci:` for fixes or improvements in the CI process
+* `doc:` for fixes and improvements in the documentation
+
+These prefix words are for conventional purposes. Use common sense and make
+the commit message clear so that others can understand what the change is.
+
+The rest of the first line should start with a verb. Examples:
+
+```text
+foo: fix typos
+```
+
+```text
+foo: resolve race condition in bar()
+```
+
+The first line should make sense when reading _"When you merge this, it will
+`$THE_FIRST_LINE`"_.
+
+The second line of the commit message must be an empty line.
+
+In the rest of the commit message, write details of the change if necessary.
+Explain what it does _and_ *why*.  The lines in the commit message should be
+limited to 72 characters or less where possible.
+
+Include a reference to an Issue when the commit fixes an Issue.
+
+```text
+fixes #$ISSUE_NUMBER
+```
+
+When an Issue number or a Pull Request number is prefixed with certain
+keywords, the referenced Issue or Pull Request will be closed. See [Linking a
+pull request to an issue using a keyword](https://docs.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)
+for the supported keywords.
+
+### Updating README.md
+
+Each component has a `.eil.yml` file in its component directory. The file is a
+metadata file of the component. If you change the file, you need to update the
+`README.md` in the project root directory. The `README.md` is generated from
+the metadata and a template, `README.md.erb`. Generate `README.md` by:
+
+```console
+bundle exec rake -C devtools readme > README.md
+```
+
+See also [`Metadata.md`](Metadata.md).
+
+### Creating a Pull Request
+
+To test your code, you need to create a Pull Request. It is not practical to
+test code manually because you have to perform many tests. For instance, the
+number of tests is all targets (`esp32`, `esp8266`, `esp32s2`, etc) * build
+methods (`make` and `idf.py`) * supported `esp-idf` versions. Let the CI do it
+for you.
+
+Before creating a Pull Request, make sure:
+
+1. You compiled the code and the build succeeded
+1. Functions, macros, data types are documented in the code
+1. An example application is provided under [`examples`](examples). In the
+   directory, create a directory `${COMPONENT_NAME}/default`. For instance, a
+   component `foo` must have `examples/foo/default`. Create an example
+   application in that directory.
+1. Update [.github/labeler.yml](.github/labeler.yml). The component should
+   have a label for it.
+1. You compiled the example code and the example application ran on a
+   physical device as expected and documented
+1. All files are licensed under one of [Acceptable Licenses](#acceptable-licenses)
+   by including the license at the top of file
+1. One of your commits in the feature branch, or the PR itself, mentions Issue
+   number so that the Issue will be automatically closed when the PR is merged
+
+When a PR is created, GitHub Actions workflows will:
+
+* label the PR with various labels, such as type of the PR (bug fix, or
+  feature)
+* perform necessary tests depending on the changes (build the examples in a
+  matrix if the source code is modified, build the documentation if files
+  under `docs` are modified)
+
+After the CI processes complete, you will see "All checks have passed" or some
+failures in the PR. To merge the PR, all checks must pass. Log is available
+from the link, `Details`, in the failed test.
+
+If the PR does not pass the CI, update the branch with a fix. At this point,
+`git rebase` may be used. For instance, if a commit has a typo and one of the
+test fails because of syntax error, commit a fix of the syntax error and do
+`git rebase` to merge the fix into the original commit that has introduced the
+syntax error.
+
+```console
+git add path/to/file
+git commmit -v
+git rebase -i master
+```
+
+`-i`, or `--interactive`, flag will launch a text editor where the history of
+the branch can be edited with commands. The buffer of the editor will look
+like:
+
+```text
+pick f7f3f6d bugfix: fix issue foo
+pick 310154e bugfix: fix a syntax error in f7f3f6d
+```
+
+The second commit, `310154e`, should be part of the previous, `f7f3f6d`. To
+rewrite the commit history, replace `pick` with `fixup`.
+
+```text
+pick f7f3f6d bugfix: fix issue foo
+fixup 310154e bugfix: fix a syntax error in f7f3f6d
+```
+
+When you save and exit the editor, `git` rewrites the commit history as if
+`310154e` was never committed. The commit `310154e` is now part of `f7f3f6d`.
+If you don't save or modify the buffer, `git` will not rewrite the commit
+history.
+
+`git rebase` can be used to tidy up the commits. To `rebase` or not to
+`rebase` depends on the nature of commits. A single commit per PR is preferred,
+but is not mandatory.
+
+See also
+[7.6 Git Tools - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History).
+
+When all the tests pass, ask the code owner to review the PR. The code owner
+can be found in `.eli.yml` file in the component directory.  From this point,
+you should avoid to `git rebase` your feature branch. Otherwise, the reviewer
+would have to review the PR from scratch.
+
+Developers who has write access to the repository will leave comments, ask
+rewrites, and merge the PR.
+
+## Licenses
+
+We provide code that can be freely used, copied, modified, and distributed by
+anyone and for any purpose.
+
+### Acceptable licenses
+
+We accept permissive licenses such as:
+
+* [ISC](https://spdx.org/licenses/ISC.html) License
+* [MIT](https://spdx.org/licenses/MIT.html) License
+* [BSD-2-Clause](https://spdx.org/licenses/BSD-2-Clause.html) License
+
+A list of licenses are available at
+[SPDX License List](https://spdx.org/licenses/).
+
+### Acceptable license for new code
+
+New code is the one you own (you wrote it from scratch). The preferred
+license to be applied to new code is a simplified ISC License. The license
+must be included at the top in every files as long as practically possible.
+The following is a preferred wording of the license.
+
+```c
+/*
+ * SPDX-License-Identifier: ISC
+ *
+ * Copyright (c) YYYY YOUR NAME HERE <user@your.dom.ain>
+ *
+ * Permission to use, copy, modify, and distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+ ```
+
+Add `SPDX-License-Identifier: $YOUR_LICENSE` to your license header.
+`$YOUR_LICENSE` is a SPDX License Identifier.
+
+* [ISC](https://spdx.org/licenses/ISC.html)
+* [BSD-2-Clause](https://spdx.org/licenses/BSD-2-Clause.html)
+
+### Unacceptable licenses
+
+We do NOT accept `copyleft` licenses such as:
+
+* GPL License
+* LGPL License
+* GNU Affero General Public License (AGPL)
+
+We do NOT accept _long_ licenses. A license is considered as _long_ when
+it has more than four clauses.
+
+We do NOT accept protective licenses that have additional restrictions, such
+as:
+
+* Apache license version 2 or later
+* various so-called _Shareware_ or _Freeware_

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/esp-idf-lib/FAQ.md	Mon Mar 27 22:13:21 2023 +0200
@@ -0,0 +1,145 @@
+# FAQ
+
+<!-- vim-markdown-toc GFM -->
+
+* [How to debug I2C-based drivers?](#how-to-debug-i2c-based-drivers)
+* [Why are semaphores (mutexes) used in i2cdev routines?](#why-are-semaphores-mutexes-used-in-i2cdev-routines)
+* [How can I connect multiple I2C devices?](#how-can-i-connect-multiple-i2c-devices)
+* [How can I change frequency of I2C clock? At default frequency my device is unstable or not working at all.](#how-can-i-change-frequency-of-i2c-clock-at-default-frequency-my-device-is-unstable-or-not-working-at-all)
+* [How to use internal pull-up resistors](#how-to-use-internal-pull-up-resistors)
+* [Can I use I2C device drivers from interrupts?](#can-i-use-i2c-device-drivers-from-interrupts)
+* [Porting I2C libs to I2Cdev](#porting-i2c-libs-to-i2cdev)
+
+<!-- vim-markdown-toc -->
+
+## How to debug I2C-based drivers?
+
+Common causes of I2C issues are:
+
+* wrong wiring
+* wrong pull-up resistors
+* wrong I2C address
+* broken I2C module
+* the driver has a bug
+
+When any of I2C-based drivers does not work, follow the steps below.
+
+Build an [_I2C scanner_ device](examples/i2c_scanner). The device is not
+necessarily an ESP device. There are many examples for various platforms.
+Search by keyword `i2c scanner`.
+
+Connect the I2C module to the I2C scanner device. Make sure appropriate
+pull-up resistors are connected to `SCL` and `SDA` lines.
+
+Scan devices on the I2C bus. If the scanner does not find the I2C device, then
+your wiring might have issues. If the scanner finds the I2C device, make sure
+the address found is what the driver expects. If you have more than one same
+I2C modules, try them all.
+
+If the scanner finds the I2C device and you are sure that the wiring is
+correct, see the signals on the wire using an oscilloscope. Most oscilloscopes
+can decode I2C signals and display I2C transactions in human-readable way.
+
+If the driver does not work after these steps, please [let us
+know](https://github.com/UncleRus/esp-idf-lib/issues).
+
+## Why are semaphores (mutexes) used in i2cdev routines?
+
+i2cdev uses two types of mutexes: port and transactional.
+
+Port mutexes (there are only two of them, by the number of I2C ports) are
+necessary to avoid problems in the situation mentioned in the documentation:
+
+> The I2C APIs are not thread-safe, if you want to use one I2C port in
+different tasks, you need to take care of the multi-thread issue.
+
+They are taken before executing single I2C transactions and are released
+immediately after them.
+
+Mutexes of the second type are created one per device and are necessary if
+the same device is used in several tasks:
+
+```C
+static i2c_dev_t some_dev;
+
+void task1(void *arg)
+{
+     // some_dev used here
+}
+
+void task2(void *arg)
+{
+     // and here some_dev used too
+}
+
+...
+xTaskCreate(task1, "task1", ....);
+xTaskCreate(task2, "task2", ....);
+
+```
+
+These mutexes are used when single device operation requires several I2C
+transactions in a row.
+
+## How can I connect multiple I2C devices?
+
+With i2cdev, you can use almost any way to connect I2C devices.
+
+For example, in the case of using SSD1306 and two MCP3428s, I would recommend
+connecting them like this:
+
+* 2 GPIO outputs on ESP32 for dedicated screen connection via I2C bus 0
+* 2 GPIO outputs to the second I2C bus, to which 2 MCP3428 are connected with
+  different addresses.
+
+If you need to connect more than one sensor with the same addresses and there
+are free GPIOs, then you can directly connect these sensors to individual GPIO
+outputs instead of using the I2C multiplexer. i2cdev will take care of
+reconfiguring I2C driver to the according outputs when you exchange data
+with these devices.
+
+## How can I change frequency of I2C clock? At default frequency my device is unstable or not working at all.
+
+You can change the frequency after initializing the device handler, like this:
+
+```C
+#include <esp_idf_lib_helpers.h>
+
+...
+
+ESP_ERROR_CHECK(ads111x_init_desc(&dev, addr, I2C_PORT, SDA_GPIO, SCL_GPIO));
+
+#if HELPER_TARGET_IS_ESP32
+    dev.cfg.master.clk_speed = 100000; // Hz
+#endif
+
+ESP_ERROR_CHECK(ads111x_set_mode(&dev, ADS111X_MODE_CONTINUOUS));    // Continuous conversion mode
+ESP_ERROR_CHECK(ads111x_set_data_rate(&dev, ADS111X_DATA_RATE_32)); // 32 samples per second
+...
+```
+
+## How to use internal pull-up resistors
+
+Just enable them in `i2c_dev_t` config. For example:
+
+```C
+...
+
+dev.cfg.scl_pullup_en = true;
+dev.cfg.sda_pullup_en = true;
+ESP_ERROR_CHECK(ads111x_init_desc(&dev, addr, I2C_PORT, SDA_GPIO, SCL_GPIO));
+
+...
+```
+
+## Can I use I2C device drivers from interrupts?
+
+With default configuration you can't. Since the drivers use mutexes, this will
+crash the system.  But you can disable use of any I2C mutexes (both port and
+device) in configuration: just enable CONFIG_I2CDEV_NOLOCK. Keep in mind that
+after enabling this option all i2c device drivers will become non-thread safe.
+
+
+## Porting I2C libs to I2Cdev
+
+See [porting.md](docs/porting.md).

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/esp-idf-lib/Gemfile	Mon Mar 27 22:13:21 2023 +0200
@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "irb"
+gem "rake"
+gem "rspec"
+gem "rubocop"
+gem "io-console", ">= 0.5.11"

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/esp-idf-lib/Gemfile.lock	Mon Mar 27 22:13:21 2023 +0200
@@ -0,0 +1,58 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    diff-lcs (1.4.4)
+    io-console (0.5.11)
+    irb (1.3.7)
+      reline (>= 0.2.7)
+    parallel (1.21.0)
+    parser (3.0.2.0)
+      ast (~> 2.4.1)
+    rainbow (3.0.0)
+    rake (13.0.6)
+    regexp_parser (2.1.1)
+    reline (0.2.7)
+      io-console (~> 0.5)
+    rexml (3.2.5)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.3)
+    rubocop (1.22.3)
+      parallel (~> 1.10)
+      parser (>= 3.0.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.12.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.13.0)
+      parser (>= 3.0.1.1)
+    ruby-progressbar (1.11.0)
+    unicode-display_width (2.1.0)
+
+PLATFORMS
+  amd64-freebsd-14
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  io-console (>= 0.5.11)
+  irb
+  rake
+  rspec
+  rubocop
+
+BUNDLED WITH
+   2.2.19

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/esp-idf-lib/Metadata.md	Mon Mar 27 22:13:21 2023 +0200
@@ -0,0 +1,309 @@
+# Metadata
+
+## Table of Contents
+
+<!-- vim-markdown-toc GFM -->
+
+* [Purpose](#purpose)
+* [Files](#files)
+    * [`.eil.yml`](#eilyml)
+    * [`persons.yml`](#personsyml)
+    * [`groups.yml`](#groupsyml)
+    * [`targets.yml`](#targetsyml)
+* [Resources](#resources)
+    * [Person](#person)
+    * [Target](#target)
+    * [License](#license)
+    * [Copyright](#copyright)
+    * [Group](#group)
+    * [Metadata](#metadata)
+    * [Component](#component)
+* [Usages of metadata in the project](#usages-of-metadata-in-the-project)
+    * [Validating metadata of components](#validating-metadata-of-components)
+    * [Generating `README.md`](#generating-readmemd)
+* [Known issues](#known-issues)
+    * [conditional `depends`](#conditional-depends)
+
+<!-- vim-markdown-toc -->
+
+This document describes metadata used in the project. The status of the
+document is beta.
+
+## Purpose
+
+The purpose of metadata in the project is to automate works in development and
+project management, to ensure the project policies, and to extend the project
+to support third-party projects.
+
+## Files
+
+### `.eil.yml`
+
+The metadata file of a component.  Each component must have `.eil.yml` in the
+root directory of the component. The file format is YAML.
+
+An example path: `components/ads111x/.eil.yml`.
+
+### `persons.yml`
+
+`persons.yml` is a YAML file that contains a list of `Person`s.
+
+### `groups.yml`
+
+`groups.yml` is a YAML file that contains a list of `Group`s.
+
+### `targets.yml`
+
+`targets.yml` is a YAML file that contains a list of `Target`s.
+
+## Resources
+
+Resources defined here represents various objects used in the metadata.
+
+A resource has unique `name` as a primary key.
+
+When referring to a resource in another resource, use `name` as key and its
+value to identify the resource. As a shorthand, you may use the name of a
+resource as `String`. In this case, the value is assumed to be `name: $VALUE`.
+
+When a resource expects a `Person` as a value,
+
+```yaml
+foo:
+  name: trombik
+```
+
+This is a shorthand version of the above example:
+
+```yaml
+foo: trombik
+```
+
+### Person
+
+A `Person` represents a person. `Person` is used to describe a copyrights
+holder and a code owner. A `Person` must be defined in `persons.yml` file.
+
+| Name | Type | Description | Required |
+|------|------|-------------|----------|
+| `name` | `String` | A unique ID string of the person. Use GitHub account or GitHub project if the person has one | Yes |
+| `full_name` | `String` | Full name of the person or the project | No |
+| `gh_id` | `String` | GitHub account name or project name | No |
+| `email` | `String` | Email address of the person | No |
+| `website` | `String` | Web site URL | No |
+
+When any of `gh_id`, `email`, or `website` is not available, `person` must
+have a full name because it is used to identify the source of code.
+
+If the person does not have `gh_id`, use the full name for `name`. For example,
+when the full name is "Foo Bar", use `name: FooB`.
+
+`Person` should have one or more of optional keys so that one can contact the
+person.
+
+Examples:
+
+```yaml
+name: trombik
+gh_id: trombik
+full_name: Tomoyuki Sakurai
+email: y@trombik.org
+website: https://github.com/trombik
+```
+
+```yaml
+name: foo
+full_name: Foo `bar` buz
+# XXX other keys are optional, but strongly recommended.
+```
+
+### Target
+
+| Name | Type | Description | Required |
+|------|------|-------------|----------|
+| `name` | `String` | Name of the build target in `esp-idf`, or `esp8266`. | Yes |
+
+An example:
+
+```yaml
+name: esp32
+```
+
+### License
+
+| Name | Type | Description | Required |
+|------|------|-------------|----------|
+| `name` | `String` | SPDX License Identifier (see [the list of licenses](https://spdx.org/licenses/)) | Yes |
+
+An example:
+
+```yaml
+name: BSD-3
+```
+
+### Copyright
+
+| Name | Type | Description | Required |
+|------|------|-------------|----------|
+| `author` | `Person` | Copyrights holder. See also `Person`. | No |
+| `name` | `String` | The value of `name` of `Person`. A shorthand for `author` | No |
+| `year` | `Integer` | Registration year of the copyrights | Yes |
+
+`Copyright` must have only one of `author` and `name`, not both.
+
+Examples:
+
+```yaml
+name: trombik
+year: 2021
+```
+
+The above example is a shorthand form of:
+
+```yaml
+author:
+  name: trombik
+year: 2021
+```
+
+### Group
+
+A `Group` represents a group of `Component`s. A `Group` must be in
+`groups.yml`.
+
+| Name | Type | Description | Required |
+|------|------|-------------|----------|
+| `name` | `String` | A unique ID of the group | Yes |
+| `description` | `String` | Description of the group | Yes |
+
+`name` should be short, and memorable. Use `-` as a word separator. It must
+not include spaces (`[0-9a-zA-Z-]+` in regular expression).
+
+An example:
+
+```yaml
+name: adc-dac
+description: ADC/DAC libraries
+```
+
+### Metadata
+
+`Metadata` is the content of `.eil.yml`. `Metadata` includes non-empty list of
+`Component` under `components` top level key.
+
+An example:
+
+```yaml
+---
+components:
+  - name: foo
+  # ... other keys go here ...
+```
+
+### Component
+
+| Name | Type | Description | Required |
+|------|------|-------------|----------|
+| `name` | `String` | The name of the component. Must be unique. | Yes |
+| `description` | `String` | A short description of the component. | Yes |
+| `group` | `Group` | The primary group name of the component. | Yes |
+| `groups` | A list of `Group` | A list of zero or more of `Group` | No |
+| `code_owners` | A list of `Person` | A list of one or more of `Person` | Yes |
+| `depends` | A list of `Component` | Zero or more of `component` that the component depends on | No |
+| `thread_safe` | `Strnig` | One of `yes`, `no`, and `N/A` | Yes |
+| `targets` | A list of `Target` | One or more of supported `target` | Yes |
+| `licenses` | A list of `License` | One or more of licenses used in the component | Yes |
+| `copyrights` | A list of `Copyright` | One or more of copyright holder | Yes |
+
+FIXME `depends` must be a list because some drivers have conditional `REQUIRES`
+in `CMakeLists.txt`.
+
+## Usages of metadata in the project
+
+The current implementation uses `ruby` and `rspec` ruby gem to validate
+metadata in all components, and generate `README.md`.
+
+Requirements are:
+
+* `ruby` 2.7 (other version should also work)
+* [`bundler`](https://bundler.io/)
+
+After installing requirements, run:
+
+```console
+bundle install
+```
+
+### Validating metadata of components
+
+To validate metadata, run:
+
+```console
+bundle exec rake -C devtools rspec
+```
+
+The implementation uses `rspec` to validate metadata because:
+
+1. the output is readable
+2. requires less `ruby` knowledge to maintain the spec than validating
+   everything in ruby code
+3. porting tests to other languages is easier than porting ruby code
+
+Under `spec` directory, there are:
+
+* `spec_helper.rb`, which is a helper for the test
+* `*_spec.rb`, which is a test script
+* other ruby files, such as `person.rb`, which are class definitions used in
+  the test
+
+The ruby classes for the test validate minimum requirements only, such as the
+`.eil.yml` file exists, or a resource has a required primary key. Actual
+test should be performed in `*_spec.rb` files.
+
+### Generating `README.md`
+
+`README.md` is generated from the metadata and `README.md.erb`. To update
+`README.md`, run the following command at the repository root directory:
+
+```console
+bundle exec rake -C devtools readme > README.md
+```
+
+## Known issues
+
+### conditional `depends`
+
+Some `CMakeLists.txt` conditionally sets `REQUIRES`. `depends` does not handle
+the following case.
+
+```yaml
+# for esp32
+depends:
+  - name: driver
+  - name: freertos
+  - name: log
+```
+
+```yaml
+# for esp8266
+depends:
+  - name: esp8266
+  - name: freertos
+  - name: log
+```
+
+A possible solution:
+
+```yaml
+depends:
+  - name: driver
+    target:
+      - name: esp32
+      - name: esp32s2
+      - name: esp32c3
+  - name: esp8266
+    target:
+      - name: esp8266
+  - name: freertos
+  - name: log
+```