Merge branch 'current' into next

This commit is contained in:
Jesse Hills 2024-06-02 09:18:57 +00:00
commit e520d41dc6
No known key found for this signature in database
GPG Key ID: BEAAE804EFD8E83A
23 changed files with 278 additions and 71 deletions

2
.gitignore vendored
View File

@ -11,3 +11,5 @@ venv
.vscode
*.DS_Store
/.idea/
_pagefind/

View File

@ -9,8 +9,22 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
software-properties-common \
&& apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/*
ENV PAGEFIND_VERSION="1.1.0"
ARG TARGETARCH
SHELL ["/bin/bash", "-c"]
RUN <<EOF
export TARGETARCH=${TARGETARCH/arm64/aarch64}
export TARGETARCH=${TARGETARCH/amd64/x86_64}
curl -o pagefind.tar.gz https://github.com/CloudCannon/pagefind/releases/download/v$PAGEFIND_VERSION/pagefind-v$PAGEFIND_VERSION-$TARGETARCH-unknown-linux-musl.tar.gz -L
tar xzf pagefind.tar.gz
rm pagefind.tar.gz
mv pagefind /usr/bin
chmod +x /usr/bin/pagefind
EOF
RUN useradd -ms /bin/bash esphome
USER esphome
WORKDIR /workspaces/esphome-docs

View File

@ -4,21 +4,21 @@ PAGEFIND_VERSION=1.1.0
PAGEFIND=pagefind
NET_PAGEFIND=../pagefindbin/pagefind
.PHONY: html html-strict cleanhtml deploy help live-html live-pagefind Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify
.PHONY: pagefind build-html html html-strict cleanhtml deploy help live-html live-pagefind Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify
html:
html: pagefind
sphinx-build -M html . _build -j auto -n $(O) -Dhtml_extra_path=_redirects,_pagefind
pagefind:
sphinx-build -M html . _build -j auto -n $(O)
mkdir -p _pagefind/pagefind
${PAGEFIND}
live-html: html
sphinx-autobuild . _build -j auto -n $(O) --host 0.0.0.0
live-pagefind: html
${PAGEFIND} --serve
live-html: pagefind
sphinx-autobuild . _build -j auto -n $(O) --host 0.0.0.0 -Dhtml_extra_path=_redirects,_pagefind
html-strict:
sphinx-build -M html . _build -W -j auto -n $(O)
${PAGEFIND}
minify:
minify _static/webserver-v1.js > _static/webserver-v1.min.js
@ -43,7 +43,9 @@ api:
net-html:
sphinx-build -M html . _build -j auto -n $(O)
mkdir -p _pagefind/pagefind
${NET_PAGEFIND}
sphinx-build -M html . _build -j auto -n $(O) -Dhtml_extra_path=_redirects,_pagefind
netlify-api: netlify-dependencies
mkdir -p _build/html/api
@ -60,9 +62,9 @@ netlify-dependencies: pagefind-binary
pagefind-binary:
mkdir -p ../pagefindbin
curl -o pagefind-v$(PAGEFIND_VERSION)-x86_64-unknown-linux-musl.tar.gz https://github.com/CloudCannon/pagefind/releases/download/v$(PAGEFIND_VERSION)/pagefind-v$(PAGEFIND_VERSION)-x86_64-unknown-linux-musl.tar.gz -L
tar xzf pagefind-v$(PAGEFIND_VERSION)-x86_64-unknown-linux-musl.tar.gz
rm pagefind-v$(PAGEFIND_VERSION)-x86_64-unknown-linux-musl.tar.gz
curl -o pagefind.tar.gz https://github.com/CloudCannon/pagefind/releases/download/v$(PAGEFIND_VERSION)/pagefind-v$(PAGEFIND_VERSION)-x86_64-unknown-linux-musl.tar.gz -L
tar xzf pagefind.tar.gz
rm pagefind.tar.gz
mv pagefind ${NET_PAGEFIND}
@ -74,6 +76,10 @@ netlify: netlify-dependencies netlify-api net-html copy-svg2png
lint: html-strict
python3 lint.py
clean:
rm -rf _pagefind/
sphinx-build -M clean . _build $(O)
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile

View File

@ -1,3 +1,9 @@
/* provide this to be queried in JS. Sadly can't be used in media-queries just yet*/
:root {
--mobile-width-stop: 875;
}
.row-odd {
background-color: #f3f6f6;
}
@ -263,9 +269,8 @@ div.body p, div.body dd, div.body li, div.body blockquote {
.search-results {
background-color: #f8f8f8;
box-shadow: 0 6px 10px rgb(0 0 0 / 0.2);
position: absolute;
position: fixed;
z-index: 1500;
margin-top: 4px;
padding-right: 6px;
padding-left: 6px;
border-radius: 12px;
@ -277,6 +282,21 @@ div.body p, div.body dd, div.body li, div.body blockquote {
display: none;
}
@media screen and (max-width: 875px) {
/* hide search result thumbnails on mobile */
.pagefind-modular-list-thumb {
width: 0;
}
/* reduce height of search box */
.pagefind-modular-input-wrapper {
scale: 90%;
}
.logo {
scale: 60%;
}
}
/* dark theme */
@media (prefers-color-scheme: dark) {
@ -383,6 +403,7 @@ div.body p, div.body dd, div.body li, div.body blockquote {
.pagefind-ui__form, .pagefind-modular-input, .search-results {
color: #ececec !important;
}
:root {
--pagefind-ui-primary: #eeeeee;
--pagefind-ui-text: #eeeeee;

View File

@ -26,7 +26,8 @@
<meta name="HandheldFriendly" content="True">
<meta name="MobileOptimized" content="320">
<meta property="og:site_name" content="ESPHome">
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">
<meta name="viewport"
content="width=device-width, initial-scale=1, maximum-scale=3, interactive-widget=overlays-content">
{% endblock %}
{% block relbar_top %}
@ -39,7 +40,6 @@
{% endif %}
</ul>
<div class="search-results" id="search-results"></div>
{% endblock %}
{% block footer %}

View File

@ -1,42 +1,150 @@
<script src="/pagefind/pagefind-modular-ui.js"></script>
<div class="pagefind-ui__form" id="search"></div>
<div class="search-results" id="mobile-search-results"></div>
<script>
let callbackAdded = null;
class El {
constructor(tagname) {
this.element = document.createElement(tagname);
}
id(s) {
this.element.id = s;
return this;
}
class(s) {
this.element.classList.add(s);
return this;
}
attrs(obj) {
for (const [k,v] of Object.entries(obj)) {
this.element.setAttribute(k, v);
}
return this;
}
text(t) {
this.element.innerText = t;
return this;
}
html(t) {
this.element.innerHTML = t;
return this;
}
handle(e, f) {
this.element.addEventListener(e, f);
return this;
}
addTo(el) {
if (el instanceof El) {
el.element.appendChild(this.element);
} else {
el.appendChild(this.element);
}
return this.element;
}
}
window.addEventListener('DOMContentLoaded', (event) => {
const std_target = document.getElementById("search-results");
const mobile_target = document.getElementById("mobile-search-results");
const targetClass = "search-results";
const docel = document.getElementsByClassName("document");
if (docel.length === 0)
return;
const inpel = document.getElementById("search");
if (!inpel)
return;
var mobileWidth = getComputedStyle(document.body).getPropertyValue("--mobile-width-stop");
function isMobile() {
return window.innerWidth <= mobileWidth;
}
const target = document.createElement("div");
target.classList.add(targetClass);
target.id = targetClass;
target.style.display = "none";
docel.item(0).appendChild(target);
const margin = 20;
const resultTemplate = (result) => {
let wrapper = new El("li").class("pagefind-modular-list-result");
let thumb = new El("div").class("pagefind-modular-list-thumb").addTo(wrapper);
if (result?.meta?.image) {
new El("img").class("pagefind-modular-list-image").attrs({
src: result.meta.image,
alt: result.meta.image_alt || result.meta.title
}).addTo(thumb);
}
let inner = new El("div").class("pagefind-modular-list-inner").addTo(wrapper);
let title = new El("p").class("pagefind-modular-list-title").addTo(inner);
new El("a").class("pagefind-modular-list-link").text(result.meta?.title).attrs({
href: result.meta?.url || result.url
}).addTo(title);
let excerpt = new El("p").class("pagefind-modular-list-excerpt").addTo(inner);
new El("a").class("pagefind-modular-list-link").html(result.excerpt).attrs({
href: result.meta?.url || result.url
}).addTo(excerpt);
return wrapper.element;
}
function resizeTarget() {
const searchPos = inpel.getBoundingClientRect();
var leftPos;
var topPos;
var maxWidth = 650;
target.style.width = "auto;"
target.style.height = "fit-content";
target.style.maxWidth = maxWidth + "px";
let rightPos = margin;
if (isMobile()) {
// position search results left aligned with the search box, and below.
leftPos = margin / 2;
topPos = searchPos.bottom + margin / 2;
rightPos = margin / 2;
} else {
// position search results top aligned with the search box, and to its right.
leftPos = searchPos.right + margin * 2;
topPos = searchPos.top;
if (rightPos - leftPos > maxWidth)
rightPos = leftPos + maxWidth;
}
target.style.right = rightPos + "px";
target.style.top = topPos + "px";
target.style.left = leftPos + "px";
let twidth = window.innerWidth - margin - leftPos;
if (twidth > maxWidth)
twidth = maxWidth;
target.style.width = twidth + "px";
target.style.maxHeight = (window.innerHeight - margin - topPos) + "px";
}
window.addEventListener("resize", (event) => { resizeTarget(); });
function showTarget() {
var target = std_target;
if (window.innerWidth <= 875) {
target = mobile_target;
std_target.style.display = "none";
} else {
mobile_target.style.display = "none";
}
target.style.display = "block";
const rect = target.getBoundingClientRect();
const height = window.innerHeight;
target.style.width = "100%";
target.style.height = "fit-content";
target.style.maxHeight = (height - rect.top - 10) + "px";
if (!callbackAdded) {
callbackAdded = true;
if (target.style.display !== "block") {
target.style.display = "block";
document.addEventListener('click', clickCallback);
}
resizeTarget();
}
function hideTargets() {
std_target.style.display = "none";
mobile_target.style.display = "none";
std_target.style.height = "0";
mobile_target.style.height = "0";
if (callbackAdded) {
if (target.style.display !== "none") {
target.style.display = "none";
document.removeEventListener('click', clickCallback);
callbackAdded = false;
}
}
@ -57,19 +165,17 @@
}));
instance.add(new PagefindModularUI.ResultList({
containerElement: "#search-results"
}));
instance.add(new PagefindModularUI.ResultList({
containerElement: "#mobile-search-results"
containerElement: "#search-results",
resultTemplate: resultTemplate
}));
const clickCallback = (event) => {
const path = event.composedPath();
if (path.includes(std_target) || path.includes(mobile_target) || path.includes(inpel))
if (path.includes(target) || path.includes(inpel))
return;
hideTargets();
};
if (std_target && mobile_target) {
if (target) {
instance.on("results", (results) => {
if (results.results.length) {
showTarget();

View File

@ -10,8 +10,7 @@ The ``bang_bang`` climate platform allows you to regulate a value with a
.. note::
A number of people have asked about the behavior of the bang-bang controller. In version 1.15, a
:doc:`thermostat <thermostat>` component was added which behaves more like a common thermostat; it is
The :doc:`thermostat <thermostat>` component behaves more like a common thermostat; it is
essentially two bang-bang controllers in one. Please see the `Bang-bang vs. Thermostat`_ section below
if you are not sure which is appropriate for your application.

View File

@ -104,12 +104,12 @@ The ``date`` provided can be in one of 3 formats:
# String date
- datetime.date.set:
id: my_date
id: my_datetime_date
date: "2023-12-04"
# Individual date parts
- datetime.date.set:
id: my_date
id: my_datetime_date
date:
year: 2023
month: 12
@ -117,7 +117,7 @@ The ``date`` provided can be in one of 3 formats:
# Using a lambda
- datetime.date.set:
id: my_date
id: my_datetime_date
date: !lambda |-
// Return an ESPTime struct
return {.day_of_month: 4, .month: 12, .year: 2023};
@ -143,7 +143,7 @@ advanced stuff (see the full API Reference for more info).
.. code-block:: cpp
// Within lambda, set the date to 2024-02-25
auto call = id(my_date).make_call();
auto call = id(my_datetime_date).make_call();
call.set_date("2024-02-25");
call.perform();
@ -175,12 +175,12 @@ The ``time`` provided can be in one of 3 formats:
# String time
- datetime.time.set:
id: my_time
id: my_datetime_time
time: "12:34:56"
# Individual time parts
- datetime.time.set:
id: my_time
id: my_datetime_time
time:
hour: 12
minute: 34
@ -188,7 +188,7 @@ The ``time`` provided can be in one of 3 formats:
# Using a lambda
- datetime.time.set:
id: my_time
id: my_datetime_time
time: !lambda |-
// Return an ESPTime struct
return {.second: 56, .minute: 34, .hour: 12};
@ -213,7 +213,7 @@ advanced stuff (see the full API Reference for more info).
.. code-block:: cpp
// Within lambda, set the time to 12:34:56
auto call = id(my_time).make_call();
auto call = id(my_datetime_time).make_call();
call.set_time("12:34:56");
call.perform();
@ -228,7 +228,7 @@ advanced stuff (see the full API Reference for more info).
.. code-block:: cpp
// For example, create a custom log message when a value is received:
ESP_LOGI("main", "Value of my datetime: %0d:%02d:%02d", id(my_time).hour, id(my_time).minute, id(my_time).second);
ESP_LOGI("main", "Value of my datetime: %0d:%02d:%02d", id(my_datetime_time).hour, id(my_datetime_time).minute, id(my_datetime_time).second);
DateTime Automation

View File

@ -13,7 +13,7 @@ using :ref:`lambdas <config-lambda>`.
datetime:
# Example Date
- platform: template
id: my_date
id: my_datetime_date
type: date
name: Pick a Date
optimistic: yes
@ -22,7 +22,7 @@ using :ref:`lambdas <config-lambda>`.
# Example Time
- platform: template
id: my_time
id: my_datetime_time
type: time
name: Pick a Time
optimistic: yes

View File

@ -360,8 +360,7 @@ You can display current time using a time component. Please see the example :ref
Screen Clipping
---------------
Screen clipping is a new set of methods since version 2023.2.0 of esphome. It could be useful when you just want to show
a part of an image or make sure that what you draw on the screen does not go outside a specific region on the screen.
Screen clipping can be useful when you just want to show a part of an image or make sure that what you draw on the screen does not go outside a specific region on the screen.
With ``start_clipping(left, top, right, bottom);`` start you the clipping process and when you are done drawing in that region
you can stop the clipping process with ``end_clipping();`` . You can nest as many ``start_clipping();`` as you want as long

View File

@ -233,7 +233,7 @@ Configuration examples
.. note::
Revision 5 and below of the wESP32 board use the LAN8720 Ethernet PHY. Revision 7 and newer of it use the RTL8201 Ethernet PHY. Support for RTL8201 is available from ESPHome version 2022.12 upwards.
Revision 5 and below of the wESP32 board use the LAN8720 Ethernet PHY. Revision 7 and newer of it use the RTL8201 Ethernet PHY.
**OpenHacks LAN8720**:

View File

@ -92,6 +92,7 @@ Event Automation
************
This automation will be triggered when an event of the specified types is triggered.
In :ref:`Lambdas <config-lambda>` you can get the event type from the trigger with ``event_type``.
.. code-block:: yaml
@ -100,7 +101,8 @@ This automation will be triggered when an event of the specified types is trigge
# ...
on_event:
then:
- logger.log: "Event Triggered"
- lambda: |-
ESP_LOGD("main", "Event %s triggered.", event_type.c_str());
Configuration variables: see :ref:`Automation <automation>`.

38
components/host.rst Normal file
View File

@ -0,0 +1,38 @@
HOST Platform
=============
.. seo::
:description: Configuration for the host platform for ESPHome.
:image: host.svg
The ``host`` platform allows ESPHome configurations to be compiled and run on a desktop computer. This is known
to work on MacOS and Linux. On Windows `WSL <https://learn.microsoft.com/en-us/windows/wsl/install>`_ (Windows Subsystem for Linux) can be used to create a Linux environment that will run ESPHome.
The only configuration required is to optionally set a dummy MAC address that will be used to identify the
configuration to Home Assistant (the native MAC address is not readily available.)
.. note::
HA will not automatically discover an ESPHome instance running on ``host`` using MDNS, and you will need
to add it explicitly using the IP address of your host computer.
Many components, especially those interfacing to actual hardware, will not be available when using ``host``. Do not
configure wifi - network will automatically be available using the host computer.
.. code-block:: yaml
# Example configuration entry
host:
mac_address: "98:35:69:ab:f6:79"
Configuration variables:
------------------------
- **mac_address** (**Optional**, MAC address): A dummy MAC address to use when communicating with HA.
See Also
--------
- :doc:`esphome`
- :ghedit:`Edit`

View File

@ -58,7 +58,7 @@ Microphone Triggers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This trigger will fire when new data is received from the microphone.
The data is available as a ``std::vector<uint8_t>`` in the variable ``x``.
The data is available as a ``std::vector<int16_t>`` in the variable ``x``.
.. code-block:: yaml

Binary file not shown.

Before

Width:  |  Height:  |  Size: 4.5 KiB

After

Width:  |  Height:  |  Size: 6.1 KiB

View File

@ -10,7 +10,6 @@ was compiled against as a text sensor.
.. figure:: images/version-ui.png
:align: center
:width: 80.0%
.. code-block:: yaml
@ -40,7 +39,7 @@ Disabling the compilation timestamp:
This will, for example, change the output of the sensor from:
``1.15.0-dev (Jun 8 2020, 18:53:16)`` to ``1.15.0-dev``
``2024.6.0-dev May 30 2024, 09:07:35`` to just ``2024.6.0-dev``
See Also

View File

@ -70,7 +70,7 @@ Configuration variables:
- **ota** (*Optional*, boolean): Turn on or off the OTA feature inside webserver. Strongly not suggested without enabled authentication settings. Defaults to ``true``. Cannot be used with the ``esp-idf`` framework.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **local** (*Optional*, boolean): Include supporting javascript locally allowing it to work without internet access. Defaults to ``false``.
- **version** (*Optional*, string): ``1`` or ``2``. Version 1 displays as a table. Version 2 uses web components and has more functionality. Defaults to ``2``.
- **version** (*Optional*, string): ``1``, ``2`` or ``3``. Version 1 displays as a table. Version 2 uses web components and has more functionality. Version 3 uses HA-Styling. Defaults to ``2``.
To conserve flash size, the CSS and JS files used on the root page to show a simple user
interface are hosted by esphome.io. If you want to use your own service, use the

View File

@ -193,7 +193,7 @@ power saving mode.
Connecting to Multiple Networks
-------------------------------
Starting with version 1.10.0, you can give ESPHome a number of WiFi networks to connect to.
You can give ESPHome a number of WiFi networks to connect to.
ESPHome will then attempt to connect to the one with the highest signal strength.
To enable this mode, remove the ``ssid`` and ``password`` options from your wifi configuration

View File

@ -168,8 +168,8 @@ There are several ways of doing this. See below examples to see how you can spec
Substitutions
-------------
Starting with version 1.10.0, ESPHome has a powerful new way to reduce repetition in configuration files:
Substitutions. With substitutions, you can have a single generic source file for all nodes of one kind and
ESPHome has a powerful new way to reduce repetition in configuration files: Substitutions.
With substitutions, you can have a single generic source file for all nodes of one kind and
substitute expressions in.
.. code-block:: yaml

19
images/host.svg Normal file
View File

@ -0,0 +1,19 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- Uploaded to: SVG Repo, www.svgrepo.com, Generator: SVG Repo Mixer Tools -->
<svg height="300px" width="300px" version="1.1" id="Capa_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
viewBox="0 0 34.418 34.418" xml:space="preserve">
<g>
<path style="fill:#010002;" d="M32.335,11.606h-6.533v-1.009h6.533V11.606z M32.335,12.264h-6.533v1.011h6.533V12.264z
M32.331,7.687h-6.523V9.91h6.523V7.687z M34.418,5.297v23.827c-0.001,0.357-0.292,0.648-0.65,0.648h-9.397
c-0.359,0-0.649-0.291-0.649-0.649V5.297c0-0.358,0.29-0.65,0.649-0.65h9.397C34.127,4.647,34.418,4.939,34.418,5.297z
M33.119,5.944h-8.1v22.53h8.1V5.944z M32.335,13.932h-6.533v1.008h6.533V13.932z M31.272,21.45c0,1.162-0.939,2.099-2.097,2.099
c-1.16,0-2.099-0.938-2.099-2.099c0-1.158,0.94-2.098,2.099-2.098C30.333,19.352,31.272,20.293,31.272,21.45z M30.515,21.45
c0-0.739-0.6-1.341-1.341-1.341c-0.742,0-1.342,0.601-1.342,1.341s0.6,1.34,1.342,1.34C29.915,22.79,30.515,22.19,30.515,21.45z
M21.937,9.218v13.505c0,0.814-0.655,1.473-1.461,1.473H13.18c0,0-0.414,2.948,2.212,2.948v1.475H13.18H8.758H6.546v-1.473
c2.529,0,2.212-2.948,2.212-2.948H1.465C0.656,24.198,0,23.539,0,22.725V9.218c0-0.814,0.656-1.47,1.465-1.47h19.01
C21.282,7.748,21.937,8.404,21.937,9.218z M12.332,22.394c0-0.698-0.566-1.263-1.264-1.263c-0.699,0-1.266,0.565-1.266,1.263
s0.566,1.265,1.266,1.265C11.767,23.659,12.332,23.092,12.332,22.394z M20.371,9.311H1.568v11.387H20.37h0.001
C20.371,20.698,20.371,9.311,20.371,9.311z M11.081,21.603c-0.434,0-0.785,0.352-0.785,0.785s0.352,0.785,0.785,0.785
s0.785-0.352,0.785-0.785S11.515,21.603,11.081,21.603z"/>
</g>
</svg>

After

Width:  |  Height:  |  Size: 1.6 KiB

View File

@ -131,6 +131,7 @@ Supported Microcontrollers
RP2040, components/rp2040, rp2040.svg
BK72xx, components/libretiny, bk72xx.svg
RTL87xx, components/libretiny, rtl87xx.svg
host, components/host, host.svg
Microcontroller Peripherals
---------------------------

View File

@ -1,4 +1,5 @@
site: _build/html
output_path: _pagefind/pagefind
exclude_selectors:
- "a.headerlink"
- ".toctree-wrapper"

View File

@ -5,7 +5,7 @@ Web Server API
:description: Information on Web Server APIs, including Event Source APIs and REST APIs.
:image: logo-text.svg
Since version 1.3, ESPHome includes a built-in web server that can be used to view states
ESPHome includes a built-in web server that can be used to view states
and send commands. In addition to the web-frontend available under the root index of the
web server, there's also two other features the web server currently offers: A real time event
source and REST API.