github/esphome
2
0 Fork 0
mirror of https://github.com/esphome/esphome.git synced 2026-11-09 14:45:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'clydebarrow/packet-interface-05' into clydebarrow/packet-interface-06

Browse Source 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
clydebarrowandClaude Opus 5.5 committed 2026-11-09 15:00:57 +11:00
2 parents c691a71cc5 9255b8c43c
commit 97f189578c
3585 files changed
+139785 -33794
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.agents/skills/automations/SKILL.md
+241
View File
@@ -0,0 +1,241 @@
---
name: automations
description: Write ESPHome automation building blocks - triggers (on_* keys), actions and conditions. Use when adding or changing an on_* trigger, an action such as my_component.do_something, a condition, a callback registration method (add_on_*_callback), or code that calls build_callback_automation, build_automation, register_*_action or register_*_condition.
---
# Automations: triggers, actions and conditions
Automations have three building blocks: **Triggers** (fire when something happens), **Actions** (do
something), and **Conditions** (check if something is true). The helpers named here are documented in
their docstrings in `esphome/automation.py`.
## Triggers: callback method (preferred)
Use `build_callback_automation()` for simple triggers. This eliminates the need for a C++ Trigger class by
using a lightweight pointer-sized forwarder struct registered directly as a callback. No `CONF_TRIGGER_ID`
in the schema.
**Python:**
```python
from esphome import automation
CONFIG_SCHEMA = cv.Schema(
{
cv.GenerateID(): cv.declare_id(MyComponent),
cv.Optional(CONF_ON_STATE): automation.validate_automation({}),
}
).extend(cv.COMPONENT_SCHEMA)
async def to_code(config):
var = cg.new_Pvariable(config[CONF_ID])
await cg.register_component(var, config)
for conf in config.get(CONF_ON_STATE, []):
await automation.build_callback_automation(
var, "add_on_state_callback", [(bool, "x")], conf
)
```
`build_callback_automation` arguments: `parent`, `callback_method` (C++ method name), `args` (template args
as `[(type, name)]` tuples), `config`, and optional `forwarder` (defaults to `TriggerForwarder<Ts...>`).
For boolean filtering (e.g. `on_press`/`on_release`), use built-in forwarders with `args=[]`:
```python
for conf_key, forwarder in (
(CONF_ON_PRESS, automation.TriggerOnTrueForwarder),
(CONF_ON_RELEASE, automation.TriggerOnFalseForwarder),
):
for conf in config.get(conf_key, []):
await automation.build_callback_automation(
var, "add_on_state_callback", [], conf, forwarder=forwarder
)
```
When the callback's parameters differ from the automation's arguments, or the trigger should only fire for
some values, pass `params`, `forward` and `when`; the helper then generates a capture-less lambda (stored
inline, nothing allocated). Name the parent with `automation.parent_ref(var)` and build `forward` from
`MockObj` calls, not f-strings of C++:
```python
parent = automation.parent_ref(var)
index = cg.RawExpression("index")
await automation.build_callback_automation(
var,
"add_on_state_callback",
[(cg.StringRef, "x"), (cg.size_t, "i")],
conf,
params=[(cg.size_t, "index")],
forward=[cg.StringRef(parent.option_at(index)), index],
)
```
`build_parent_callback_automation`, `build_trigger_callback`, `build_callback_automations` and
`build_trigger_automations` cover the other shapes; see their docstrings in `esphome/automation.py`.
When every action in a callback automation is inline (see Actions below), no `Automation` or action objects
are generated: the callback calls one generated function, at the same RAM cost as a hand-written lambda. A
custom forwarder blocks this unless its filter is also given as `params`, `forward` and `when`, so always pass
them together:
```python
automation.CallbackAutomation(
CONF_ON_IDLE,
"add_on_state_callback",
forwarder=StateEnterForwarder.template(State.IDLE),
params=[(State, "state")],
forward=[],
when=f"state == {State.IDLE}",
)
```
**C++: no trigger class needed.** The callback registration method must be templatized to accept both
`std::function` and lightweight forwarder structs (which avoid heap allocation):
```cpp
class MyComponent : public Component {
public:
// Must be a template -- accepts both std::function and pointer-sized forwarder structs
template<typename F> void add_on_state_callback(F &&callback) {
this->state_callback_.add(std::forward<F>(callback));
}
protected:
// Use CallbackManager when callbacks are always registered (e.g. core components)
CallbackManager<void(bool)> state_callback_;
// Use LazyCallbackManager when callbacks are often not registered -- saves 8 bytes
// (nullptr vs empty std::vector) per instance when no callbacks are added
// LazyCallbackManager<void(bool)> state_callback_;
};
```
Never type a registration method's parameter as `std::function`; that forces a heap allocation for every
forwarder struct:
```cpp
// Bad
void add_on_state_callback(std::function<void(bool)> &&callback) {
this->state_callback_.add(std::move(callback));
}
```
| Type | Idle overhead (32-bit) | When to use |
|------|----------------------|-------------|
| `CallbackManager<void(Ts...)>` | 12 bytes (empty `std::vector`) | Callbacks are always or almost always registered |
| `LazyCallbackManager<void(Ts...)>` | 4 bytes (`nullptr`) | Callbacks are often not registered (common case) |
| `AutomationList<N, Ts...>` + `build_automation_lists` | 4 bytes per automation + count, none when unused | A hub fires its own `on_*` automations with no filter (4 B per automation vs 8 B per `Callback`) |
| `automation.new_automation(args, conf)` + the parent's own fixed table | the table entry (pointer plus its own data) | Like `AutomationList`, but each automation needs a stored value of its own, e.g. a threshold the parent compares against |
Both live in `esphome/core/helpers.h` and accept `std::function`, lambdas and forwarder structs through
their templatized `add()` method. `LazyCallbackManager` is a drop-in replacement for `CallbackManager` that defers allocation until the first
callback is added. Prefer it for entity-level callbacks where most instances have no subscribers.
## Triggers: Trigger class method
Use `build_automation()` with a `Trigger<Ts...>` subclass only when the forwarder needs **mutable state
beyond a single `Automation*` pointer** (e.g. edge detection tracking previous state, timing logic).
**Python:**
```python
TurnOnTrigger = my_ns.class_("TurnOnTrigger", automation.Trigger.template())
CONFIG_SCHEMA = cv.Schema(
{
cv.Optional(CONF_ON_TURN_ON): automation.validate_automation(
{cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(TurnOnTrigger)}
),
}
)
async def to_code(config):
for conf in config.get(CONF_ON_TURN_ON, []):
trigger = cg.new_Pvariable(conf[CONF_TRIGGER_ID], var)
await automation.build_automation(trigger, [], conf)
```
**C++:**
```cpp
class TurnOnTrigger : public Trigger<> {
public:
explicit TurnOnTrigger(MyComponent *parent) : last_on_{false} {
parent->add_on_state_callback([this](bool state) {
if (state && !this->last_on_)
this->trigger();
this->last_on_ = state;
});
}
protected:
bool last_on_;
};
```
## Actions
```cpp
template<typename... Ts> class MyAction : public Action<Ts...> {
public:
explicit MyAction(MyComponent *parent) : parent_(parent) {}
void play(const Ts &...) override { this->parent_->do_something(); }
protected:
MyComponent *parent_;
};
```
Register it without writing a builder:
```python
automation.register_simple_action(
"my_component.do_something", MyAction, schema, synchronous=True
)
```
The constructor receives the object named by `config[CONF_ID]`. Use `register_bare_action` for a
no-argument constructor, `register_parented_action` for a class deriving from `Parented<T>`, and the
`@automation.register_action(...)` decorator only when the builder must also set fields.
Use `synchronous=True` for actions that run to completion inside `play()` without deferring. Use
`synchronous=False` if the action may suspend/defer execution (e.g. `delay`, `wait_until`, `script.wait`)
or store trigger arguments for later use.
**Actions that only forward templatable values to their parent need no C++ class.** Register them with
`register_apply_action`; do not write a `TEMPLATABLE_VALUE` class or a builder for this shape.
```python
automation.register_apply_action(
"my_component.set_gains",
schema,
automation.ApplyField(CONF_KP, "set_kp", cg.float_),
automation.ApplyField(CONF_KI, "set_ki", cg.float_),
)
```
The `ApplyField`, `ApplyCall` and `register_apply_action` docstrings in `esphome/automation.py` cover the
rest; `cover.control` and `cover.template.publish` are in-tree examples. An action whose input is a byte
payload passes `automation.ApplyBytes(CONF_DATA, "send({})")` in the same call; a constant payload stays in
flash and a lambda's vector is forwarded as data and size. `TEMPLATABLE_VALUE` with `cg.templatable` stays
for actions whose `play()` has real logic beyond forwarding values.
Adjacent `register_apply_action` and `lambda:` actions in a list merge into one generated function and one
object, which saves 12 to 16 bytes of RAM per merged action. An action with its own C++ class ends the merged
run, so prefer `register_apply_action` wherever the action allows it. Because of this, `build_action_list` can
return fewer objects than the config has entries. A builder that wraps `apply_action_builder` may do other work
first, but must return its result unchanged and not use it. A builder that must generate its own statements, and
is registered with `automation.ApplyAction`, can call `apply_statements_action` and still merge; `script.execute`
is an example. `if`, `choose`, `while` and `repeat` whose bodies are all inline become C++ control flow in the
same function, and `register_apply_condition` and `lambda:` conditions become plain expressions there.
## Conditions
```cpp
template<typename... Ts> class MyCondition : public Condition<Ts...> {
public:
explicit MyCondition(MyComponent *parent) : parent_(parent) {}
bool check(const Ts &...) override { return this->parent_->is_active(); }
protected:
MyComponent *parent_;
};
```
Register with `automation.register_simple_condition("my_component.is_active", MyCondition, schema)`;
`register_bare_condition`, `register_parented_condition` and the decorator follow the action rules.
**Conditions that only test their parent need no C++ class either.** Register them with
`register_apply_condition`; the expression is applied to the parent, and an `ApplyCall` compares against
config values.
```python
automation.register_apply_condition("my_component.is_active", schema, "is_active()")
automation.register_apply_condition(
"my_component.state_is",
schema,
automation.ApplyCall("state == {}", ((CONF_STATE, cg.bool_),)),
)
```
`cover.is_open`, `rtttl.is_playing` and `component.is_idle` are in-tree examples.
.agents/skills/breaking-changes/SKILL.md
+68
View File
@@ -0,0 +1,68 @@
---
name: breaking-changes
description: Decide whether an ESPHome change breaks public API and handle it - what counts as public C++ and Python API, the deprecation window, ESPDEPRECATED for C++, cv.rename_key and deprecation warnings for config keys, and the migration notes a PR needs. Use when removing, renaming or changing the signature of a config option, a public C++ member or a core Python helper.
---
# Public API and breaking changes
Full policy: https://developers.esphome.io/contributing/code/#public-api-and-breaking-changes
## What is public
- **C++ in components:** only features documented at [esphome.io](https://esphome.io) are public API.
Undocumented `public` members are internal.
- **C++ core and base classes** (`esphome/core/`, `Component`, `Sensor`, etc.): all `public` members are
public API.
- **Components with global accessors** (`global_api_server`, etc.): all `public` members are public API
(except config setters).
- **Python:** all documented configuration options are public API. Python code in `esphome/core/` that
existing core components use is stable API. Other Python code is internal unless explicitly documented
for external component use.
- Changing the signature of a lambda that code generation injects is not a breaking change.
## Policy
- Aim for a **6-month deprecation window** when possible.
- Clean breaks are allowed for signature changes, deep refactorings and resource constraints.
- The migration path goes in the PR description (it generates the release notes).
- A blog post is required for core/base class changes or significant architectural changes.
Checklist:
- [ ] Clear justification (RAM/flash savings, architectural improvement)
- [ ] Explored non-breaking alternatives
- [ ] Added deprecation warnings if possible (`ESPDEPRECATED` for C++)
- [ ] Documented migration path in the PR description with before/after examples
- [ ] Updated all internal usage and esphome.io
- [ ] Tested backward compatibility during the deprecation period
## Deprecating C++
```cpp
// Remove before 2026.6.0
ESPDEPRECATED("Use new_method() instead. Removed in 2026.6.0", "2025.12.0")
void old_method() { this->new_method(); }
```
## Deprecating config keys
For a renamed key, use the shared `cv.rename_key` validator with `removed_in` (and `component` for
context); it warns and migrates automatically:
```python
CONFIG_SCHEMA = cv.All(
cv.rename_key(
CONF_OLD_KEY, CONF_NEW_KEY, removed_in="2026.6.0", component="my_component"
),
cv.Schema({...}),
)
```
For other deprecations, warn manually during validation:
```python
# Remove before 2026.6.0
if CONF_OLD_KEY in config:
_LOGGER.warning(
f"'{CONF_OLD_KEY}' deprecated, use '{CONF_NEW_KEY}'. Removed in 2026.6.0"
)
config[CONF_NEW_KEY] = config.pop(CONF_OLD_KEY) # Auto-migrate
```
Cover the old syntax with a `validate.*.yaml` test (see the `component-tests` skill), and keep the language
schema correct (see the `config-validation` skill).
.agents/skills/code-review/SKILL.md
+72 -7
View File
@@ -9,15 +9,37 @@ ESPHome parses YAML into C++ firmware for memory-constrained microcontrollers
(ESP32, ESP8266, RP2040, LibreTiny). Review changes with that in mind: RAM and
flash are scarce, and code runs unattended for months.
`AGENTS.md` in the repository root is the full contributor guide and the
authority when it disagrees with this summary. The developer documentation at
https://developers.esphome.io explains the component lifecycle and the reasoning
behind these rules. This skill lists the concrete things worth flagging in a
review; read `AGENTS.md` for the detail behind any item.
`AGENTS.md` in the repository root is the contributor guide, and the skills it
lists (`component-codegen`, `config-validation`, `automations`,
`embedded-memory`, `component-tests`, `breaking-changes`) hold the detail. They
are the authority when they disagree with this summary. The developer
documentation at https://developers.esphome.io explains the component lifecycle
and the reasoning behind these rules. This skill lists the concrete things worth
flagging in a review; read the matching skill for the detail behind any item.
Only raise findings that the diff actually introduces or changes. Do not ask for
drive-by cleanup of pre-existing code the PR did not touch.
## Scope: shared code does not ride a component PR
Check the file list first. A PR titled for one component (`[ld2450] ...`) must
not also change code other components build on: `esphome/core/`, the entity
platform components (`esphome/components/sensor/`, `esphome/components/text_sensor/`
including its `filter.*`, `binary_sensor/`, `number/`, ...), the buses
(`esphome/components/{i2c,spi,uart}/`), `network/`, `socket/`, the shared
constants (`esphome/components/const/`, `esphome/const.py`),
`esphome/automation.py`, `esphome/cpp_generator.py` or `esphome/config_validation.py`.
Flag it and ask for the shared change to move into its own PR, which lands first
and is reviewed by that code's owners; the component PR then builds on it. This
holds even when the shared change is small or only the component uses it today.
The exception is a shared change that must update several components in the same
PR so none of them breaks in between (a `[core]` or `[components]` PR that adds a
helper and moves its callers at once).
Not shared code: the component's own platform files (`esphome/components/<c>/sensor.py`,
`text_sensor/__init__.py`, ...), its new `USE_*` lines in `esphome/core/defines.h`,
and its `CODEOWNERS` entry.
## Memory and embedded constraints (highest value)
Heap allocation after `setup()` is treated as a reliability bug, not a
@@ -28,8 +50,8 @@ performance nit, because it fragments a small shared heap. Flag:
`StaticVector<T, N>` when a `push_back` API is needed) or fixed at runtime
init (use `FixedVector<T>`).
- Listener / child-entity registration lists stored as `std::vector`; these have
a compile-time-known count and should use `cg.slot_counter()` plus
`StaticVector`.
a compile-time-known count and should use `cg.slot_list()` plus
`SLOT_LIST` (or `cg.slot_counter()` plus `StaticVector`).
- `std::vector<uint8_t>` for a byte buffer that never grows: prefer
`std::unique_ptr<uint8_t[]>` or `std::array`.
- `std::map` / `std::set` / `std::unordered_map` for small datasets (1-16
@@ -39,6 +61,12 @@ performance nit, because it fragments a small shared heap. Flag:
literal already lives in flash).
- `std::string` / `std::to_string` / string-returning helpers on hot paths where
a buffer or view API exists.
- A `set_timeout` / `set_interval` / `defer` lambda whose captures exceed 8 bytes
on 32-bit or are not trivially copyable (`this` plus two 4-byte values, `this`
plus a member function pointer, a `std::string`, a `std::function`):
`std::function` then heap-allocates each time it is scheduled. Flag it on
retries, re-armed timeouts and hot-path `defer`; a `set_interval` set up once
in `setup()` is a single allocation. `[this]` plus one 4-byte value fits.
## C++ conventions
@@ -67,6 +95,27 @@ performance nit, because it fragments a small shared heap. Flag:
typed as `std::function`, so lightweight forwarders avoid a heap allocation.
- Two-space indent, `using` over `typedef`, wrap at 120 columns.
## Use the existing helper
New components often hand-write code a helper already covers. Ask for the
helper; `AGENTS.md` section 4 and the `component-codegen` skill have the detail.
| Seen in the PR | Ask for |
| --- | --- |
| `if (this->x_sensor_ != nullptr) this->x_sensor_->publish_state(v);` | `PUBLISH_STATE(this->x_sensor_, v);` (`esphome/core/entity_base.h`) |
| set warning / `return` / clear warning around a bus result | `if (!this->status_comm_result(ok)) return;` |
| hand-written `set_x_sensor()` plus `x_sensor_` member | `SUB_SENSOR(x)`, `SUB_BINARY_SENSOR`, `SUB_TEXT_SENSOR`, `SUB_SWITCH`, ... |
| `if CONF_X in config: s = await sensor.new_sensor(config[CONF_X])` plus setter | `sensors = sensor.sub_sensors(config)` then `await sensors(CONF_X, hub.set_x_sensor)` |
| hand-written `{"a": MyEnum.MY_ENUM_A, ...}` dict | `MyEnum.options("a", "b", prefix="MY_ENUM_")` |
| loops on `available()` / `read_byte()` | UART `read_available(on_byte)`, `discard_available()`, `LineReader<N>`, `FrameReader<N, HEADER...>` |
| hand-rolled CRC, checksum or bit loop | `crc8`, `crc16`, `xor_bytes`, `sum16_bytes`, `encode_uint16`, ... (`esphome/core/helpers.h`) |
| integer split into buffer bytes by hand (`buf[0] = v >> 8; buf[1] = v;`) | `put_be16`/`24`/`32`, `put_le16`, `put_le32` (`esphome/core/helpers.h`) |
| bare `mark_failed()`, or `ESP_LOGE` then `mark_failed()` | `this->mark_failed(LOG_STR("reason"))` or `LOG_STR(ESP_LOG_MSG_COMM_FAIL)` |
| button/switch/number/select C++ class that only calls the hub | `ApplyButton`, `ApplySwitch`, `ApplyNumber`, `ApplySelect` with `apply=` |
| action or condition class that only forwards to the parent | `register_apply_action` / `register_apply_condition` |
| enum-to-string `switch` returning literals | `PROGMEM_STRING_TABLE` with `get_log_str` / `get_progmem_str` |
| `if (x := config.get(CONF_X)) is not None: cg.add(var.set_x(x))` | `cg.add_optional(var.set_x, config.get(CONF_X))`, when the setter takes the value unchanged |
## Python conventions
- Type-annotate every new function signature (params and return), new dataclass
@@ -76,6 +125,10 @@ performance nit, because it fragments a small shared heap. Flag:
`if (blah := config.get(CONF_BLAH)) is not None:`.
- Reuse existing validators from `config_validation.py` (`cv.rename_key`,
`cv.has_exactly_one_key`, etc.) via `cv.All(...)` instead of hand-rolling.
- A new or changed validator function that wraps, chooses or builds a schema
must be decorated with `@schema_extractor(...)` and handle `SCHEMA_EXTRACT`,
or `script/build_language_schema.py` silently drops the keys behind it (see
the `config-validation` skill).
- `esphome/const.py` is frozen: no new `CONF_` constants there. Define them in
the component's own `.py`, or in `esphome/components/const/__init__.py` when
shared. The same constant defined in three or more component files fails CI.
@@ -96,6 +149,18 @@ performance nit, because it fragments a small shared heap. Flag:
- Config-only checks use the `validate.*.yaml` prefix; compiled checks use
`test.*.yaml`.
## Naming user-facing functions
Documented lambda methods, actions and config keys are public API, so a bad name
is hard to fix once released. Flag:
- A boolean where `true` means off (`display_off(true)`): name the positive
state, e.g. `set_power(bool on)`.
- A name that differs from a sibling component's name for the same operation.
Before a release, rename outright; after, follow the breaking-change policy
below.
## Breaking changes and public API
- Base classes under `esphome/core/` and documented config options are public
.agents/skills/component-codegen/SKILL.md
+276
View File
@@ -0,0 +1,276 @@
---
name: component-codegen
description: Write the Python side of an ESPHome component - __init__.py and platform files (sensor.py, switch.py, ...), DOMAIN and other metadata, to_code, hub child entities with sub_sensors and friends, pins and referenced components, hub-forwarding entities (ApplyButton, ApplySwitch), uart/i2c/spi constructor helpers, and CORE.data state. Use when creating a component or changing its code generation.
---
# Component code generation
Read https://developers.esphome.io/architecture/components/ for the component lifecycle and how a
component is registered. Schema rules and schema extraction are in the `config-validation` skill;
automations (`on_*`, actions, conditions) in the `automations` skill.
## Files
```
components/[component_name]/
├── __init__.py # Component configuration schema and code generation
├── [component].h # C++ header file (if needed)
├── [component].cpp # C++ implementation (if needed)
└── [platform]/ # Platform-specific implementations
├── __init__.py # Platform-specific configuration
├── [platform].h # Platform C++ header
└── [platform].cpp # Platform C++ implementation
```
## Metadata
- `DOMAIN`: required in every component's `__init__.py`, set to the component's own name as a plain string
(e.g. `DOMAIN = "my_component"`). Other code refers to the component through it, e.g.
`from esphome.components.my_component import DOMAIN`. Keep it in alphabetical order with the other
metadata constants. CI (`lint_component_domain`) fails without it.
- `DEPENDENCIES`: list of required components.
- `AUTO_LOAD`: components to automatically load. Not a way to put entities under the component's own key;
see "Entities of a hub" below.
- `CONFLICTS_WITH`: incompatible components.
- `CODEOWNERS`: GitHub usernames responsible for maintenance.
- `MULTI_CONF`: whether multiple instances are allowed.
## Basic pattern
```python
import esphome.codegen as cg
import esphome.config_validation as cv
from esphome.const import CONF_KEY, CONF_ID
DOMAIN = "my_component"
CONF_PARAM = "param" # A constant that does not yet exist in esphome/const.py
my_component_ns = cg.esphome_ns.namespace("my_component")
MyComponent = my_component_ns.class_("MyComponent", cg.Component)
CONFIG_SCHEMA = cv.Schema(
{
cv.GenerateID(): cv.declare_id(MyComponent),
cv.Required(CONF_KEY): cv.string,
cv.Optional(CONF_PARAM, default=42): cv.int_,
}
).extend(cv.COMPONENT_SCHEMA)
async def to_code(config):
var = cg.new_Pvariable(config[CONF_ID])
await cg.register_component(var, config)
cg.add(var.set_key(config[CONF_KEY]))
cg.add(var.set_param(config[CONF_PARAM]))
```
```cpp
namespace esphome::my_component {
class MyComponent : public Component {
public:
void setup() override;
void loop() override;
void dump_config() override;
void set_key(const char *key) { this->key_ = StringRef(key); }
void set_param(int param) { this->param_ = param; }
protected:
StringRef key_;
int param_{0};
};
} // namespace esphome::my_component
```
When the setter takes the value unchanged, use `cg.add_optional(var.set_blah, config.get(CONF_BLAH))`; it
is not awaited, and it skips only `None`, so `0` and `False` are still set. Required, invariant
dependencies are constructor arguments to `cg.new_Pvariable()`, not setters.
## Entity platforms
**Sensor:**
```python
from esphome.components import sensor
CONFIG_SCHEMA = sensor.sensor_schema(MySensor).extend(
cv.polling_component_schema("60s")
)
async def to_code(config):
var = await sensor.new_sensor(config)
await cg.register_component(var, config)
```
**Binary sensor:**
```python
from esphome.components import binary_sensor
CONFIG_SCHEMA = binary_sensor.binary_sensor_schema().extend({...})
async def to_code(config):
var = await binary_sensor.new_binary_sensor(config)
```
**Switch:**
```python
from esphome.components import switch
CONFIG_SCHEMA = switch.switch_schema().extend({...})
async def to_code(config):
var = await switch.new_switch(config)
```
## Entities of a hub
A new component's entities go in platform files (`sensor.py`, `binary_sensor.py`, ...) that take the hub's
id, never under the hub's own key with their platforms added to `AUTO_LOAD` to make that work. Auto loading
a platform because the C++ uses its type is fine. See
https://developers.esphome.io/architecture/components/#exposing-multiple-entities.
```yaml
# Bad - entities under the hub's key
my_hub:
connected:
name: Connected
# Good - the hub, then one platform entry that holds its entities
my_hub:
id: hub1
binary_sensor:
- platform: my_hub
my_hub_id: hub1 # optional with a single hub
connected:
name: Connected
```
**Optional child entities of a hub:** bind the config once with `sensor.sub_sensors(config)` (or
`sub_binary_sensors`, `sub_text_sensors`, `sub_buttons`, `sub_switches`, `sub_numbers`, `sub_selects` in
their domains), adding `parent=hub` for entities that derive from `Parented<T>`, then make one call per
key, even when there is only one. A call creates the entity only when its key is configured, passes it to
the setter and returns it (or `None`); extra arguments such as `min_value` or `options` go on the call.
Always name the setter explicitly on the object that owns it, never with `getattr` and an f-string, and
keep that variable short (`var` for the component itself, `hub` for one fetched with `cg.get_variable`) so
the calls fit on one line. Loops whose setter also takes an index, such as `set_gate_threshold(x, n)`, stay
as they are.
```python
# my_hub/sensor.py
async def to_code(config):
hub = await cg.get_variable(config[CONF_MY_HUB_ID])
sensors = sensor.sub_sensors(config)
await sensors(CONF_TEMPERATURE, hub.set_temperature_sensor)
await sensors(CONF_HUMIDITY, hub.set_humidity_sensor)
# my_hub/button.py
async def to_code(config):
hub = await cg.get_variable(config[CONF_MY_HUB_ID])
buttons = button.sub_buttons(config, parent=hub)
await buttons(CONF_RESTART, hub.set_restart_button)
```
**Hub forwarding entities need no C++ class:** a button, switch, number or select that only calls its hub
uses `button.ApplyButton` (`switch.ApplySwitch`, `number.ApplyNumber`, `select.ApplySelect`) in its schema
and `apply=` on the `sub_*` call. The body is a call on the hub with `entity` and `state`, `value` or
`index`/`option` in scope; on a switch, number or select `publish="before"` or `"after"` publishes the
state, and `publish="on_success"` publishes only when the hub call returns true (a write the device can
refuse). `publish="momentary"` is only for legacy action switches (restart, factory reset): it publishes off
and runs the body only when turned on. Never use it for a new entity; an action is a button.
```python
switches = switch.sub_switches(config, parent=hub)
await switches(CONF_BLUETOOTH, None, apply="set_bluetooth(state)", publish="after")
```
Restore an owned or standalone switch in `setup()` with `sw->restore()`, or `restore(default)` to still
drive a state when the restore mode is disabled. A hub that applies its switches' restored states itself
reads `sw->get_initial_write_state()`, which already applies `inverted`.
**A hub that forwards data to its children:** when what each child does with the data is known at build time
(decode a register field, match a key or tag, publish a value), declare a `cg.HubFunction` once in the hub's
`__init__.py` and have each platform add one item per entity, built from codegen expressions. Code generation writes
one function per hub. Pass `define=` and put the hub's `HUB_PUBLISHER(<name>, args...)` (in a public section; it
ends on `public:`) and its call under that `#ifdef`; call the pointer only when it is not null. The children stay
plain entities, with no listener class or list. A child that lost a `Component` base keeps its dump lines through
a second hub function (`"dump"`, a `const char *` tag parameter, no define of its own) that the hub's
`dump_config()` calls inside the value function's `#ifdef`; every child adds to both.
**Entities that each watch a register field:** when every field (register, shift, mask, match) is known at
build time, use the rule above (see `bq25186`). A binary sensor tests its field value against an on-values
bitmap (`match`); a one-bit field reads the bit (simplified from bq25186's `_state_expression`):
```python
# hub __init__.py
STATUS_PUBLISHER = cg.HubFunction(
"status", # esphome__<hub>__status_fn, passed to HUB_PUBLISHER(status, ...)'s setter
cg.void,
[(BQ25186StatusRegisters.const_ref(), "status")],
define="USE_BQ25186_STATUS_PUBLISHER",
)
STATUS = STATUS_PUBLISHER.param("status")
# platform to_code, per configured entity
value = (STATUS[reg] >> shift) & mask
if mask != 0x01 or match != 0b10: # 0b10: a one-bit field that is on when set
value = (cg.MockObj(f"{match:#06b}") >> value) & 1
STATUS_PUBLISHER.add(hub, parent_ref(var).publish_state(value))
```
Store a field description per entity (a struct in a `SlotList` sized by `cg.slot_list`) only when the
field is chosen at run time, as in `sen6x`, where the status bit depends on the variant read in `setup()`.
Never a template per bit or a virtual listener base (a second vptr per entity).
## Other helpers
- **Pins and referenced components:** set them with `await cg.add_pin(var.set_cs_pin, config[CONF_CS_PIN])`
and `await cg.add_variable(var.set_bus, config[CONF_BUS_ID])`; both skip a `None` value, so pass
`config.get(KEY)` for an optional key, and return what they created. Use `cg.register_parented` for
`set_parent`.
- `uart.new_uart_component(config, *ctor_args)` (and `i2c.new_i2c_component`, `spi.new_spi_component`,
`modbus.new_modbus_client_component`, `ble_client.new_ble_node_component`) constructs, registers and
attaches in one call.
- A fixed buffer sized from the config is a file-scope static (BSS, not heap):
`buf = cg.static_buffer(config[CONF_ID], cg.uint8, size)`, named after its owner so `esphome analyze-memory`
counts it there; pass `buf` to the constructor.
A buffer that may live in PSRAM takes `psram=True`: PSRAM builds get a zeroed `psram_buffer<T>(size)` allocation
instead, so pass `buf` once and mark the component failed in `setup()` if it is nullptr. `align=4` emits
`alignas(4)`, so a word-aligned byte buffer stays `uint8`. `size` may be an expression such as `MyClass.static_("buffer_size")(n)`, which renders
`ns::MyClass::buffer_size(n)`.
- `display.add_writer(var, config)` sets the lambda.
- `MyEnum.options("on", prefix="MY_ENUM_")` builds an enum dict.
- `button.restart_button_schema(cls)` (and `factory_reset_`, `query_`) are button presets.
- `fv.get_declaring_config(id)` finds a hub's config in final validation.
## State during code generation
Use `CORE.data` for component state that needs to persist during configuration generation, namespaced
under the component's `DOMAIN` and held in a `@dataclass`. Avoid module-level mutable globals: they
persist between compilation runs if the host process (e.g. device-builder) doesn't fork/exec, whereas
`CORE.data` is cleared between runs.
```python
from dataclasses import dataclass, field
from esphome.core import CORE
DOMAIN = "my_component"
@dataclass
class MyComponentData:
feature_enabled: bool = False
item_count: int = 0
items: list[str] = field(default_factory=list)
def _get_data() -> MyComponentData:
if DOMAIN not in CORE.data:
CORE.data[DOMAIN] = MyComponentData()
return CORE.data[DOMAIN]
def request_feature() -> None:
_get_data().feature_enabled = True
```
Don't use flat keys such as `CORE.data["my_component_feature"] = True`. Some components use `TypedDict`
instead of a dataclass; both are acceptable.
.agents/skills/component-tests/SKILL.md
+101
View File
@@ -0,0 +1,101 @@
---
name: component-tests
description: Write and run tests for ESPHome components - YAML build tests (test.*.yaml, validate.*.yaml, common.yaml) under tests/components, shared bus packages and CI test grouping, C++ gtest unit tests, and host integration tests including the uart_mock fixture. Use when adding or changing files under tests/, or when a code change needs test coverage.
---
# Component tests
## C++ unit tests
gtests live in `tests/components/<component>/*.cpp` and run with `script/cpp_unit_test.py <component>`; see
`tests/components/README.md`. Set the loop clock in a test with `LoopBlockingGuard{nullptr, nullptr,
now_ms}`; the runner resets it before every test.
## Integration tests
`tests/integration/` runs real firmware on the host. Serial components prove timeouts and recovery with the
`uart_mock` fixture (`tests/integration/test_uart_mock_*.py`). Its `responses` match on content every time
they see it; to answer a repeated request differently, use an `on_tx` lambda with a static counter and
`inject_to_rx_buffer` (see `uart_mock_ld2412_requery_after_giveup.yaml`).
## YAML build tests
```
tests/
├── test_build_components/
│ └── common/ # Shared bus packages (uart, i2c, spi, etc.)
│ ├── uart/ # UART at default baud rate
│ ├── uart_115200/ # UART at 115200 baud
│ ├── i2c/ # I2C bus
│ └── spi/ # SPI bus
└── components/[component]/
├── common.yaml # Component-only config (no bus definitions)
├── test.esp32-idf.yaml # config + compile
├── test.esp8266-ard.yaml # config + compile
├── test-variant.esp32-idf.yaml # variant test, config + compile
├── validate.esp32-idf.yaml # config-only (never compiled)
└── validate-legacy.esp32-idf.yaml # config-only variant
```
Run them with `script/test_build_components`. Use `-c <component>` to test specific components and
`-t <target>` for specific platforms.
- **Keep build-test variants few:** one `test.<platform>.yaml` per platform the code actually differs on.
A variant per board for platform-identical code only adds CI time.
- **Config-only test files (`validate.*.yaml`):** use this prefix when a YAML file only needs to exercise
schema/validation paths and does not need to be compiled. CI runs `validate.*.yaml` files with
`esphome config` only and skips them during compile. The grammar mirrors `test.*.yaml`:
- `validate.<platform>.yaml`: base config-only test
- `validate-<variant>.<platform>.yaml`: config-only variant
Use this for deprecated-syntax migration tests, schema edge cases, or platform-specific validation
branches where building firmware adds no signal. A component may have any mix of `test.*.yaml` and
`validate.*.yaml` files. Validate files never participate in bus grouping; each one runs as its own
`esphome config` invocation.
When a PR's only edits to a component are `validate.*.yaml` files (no source changes, no `test.*.yaml`
changes, and the component isn't pulled in as a dependency of another changed component), CI skips the
compile stage for that component and only runs config validation. This is decided in
`script/determine-jobs.py` via `_component_change_is_validate_only` and surfaced as the
`validate_only_components` output that the `test-build-components-split` job consumes.
## Grouping with packages
Components that use shared bus packages can be grouped together in CI to reduce build count. **Never define
buses (uart, i2c, spi, modbus) directly in test YAML files**; always use packages from
`test_build_components/common/`.
All includes in test files must go through dict-style `packages:` so that batch grouping works; the
grouping scripts only understand dict-style packages. Never use list-style packages
(`packages: [- !include ...]`) or top-level merge keys (`<<: !include common.yaml`). Bus packages are keyed
by the bus name; the component's `common.yaml` is keyed by the component name (e.g.
`cst328: !include common.yaml`):
```yaml
# test.esp32-idf.yaml - everything included via named packages
packages:
uart: !include ../../test_build_components/common/uart_115200/esp32-idf.yaml
my_component: !include common.yaml
```
```yaml
# common.yaml - component config only, NO bus definitions
my_component:
id: my_instance
sensor:
- platform: my_component
name: My Sensor
```
Components that define buses directly are flagged as "NEEDS MIGRATION" and cannot be grouped, increasing
CI build time. `!extend` and `!remove` in a `test.*.yaml` also make the component ungroupable; add a
standalone entity with its own id instead.
A test that needs a shared component in a particular state (`esp32_ble` security settings, an option that
PSRAM rejects) cannot be grouped: the merged block wins and the whole batch fails. Add the component to
`ISOLATED_COMPONENTS` in `script/analyze_component_buses.py`, or move the option to a `test-<variant>` file.
To verify that all components can be tested together without ID conflicts or configuration issues:
```bash
./script/test_component_grouping.py -e config --all
```
This tests all components in a single build to catch conflicts that might not appear when testing
components individually. Use `-e config` for fast configuration validation, or `-e compile` for full
compilation testing.
.agents/skills/config-validation/SKILL.md
+124
View File
@@ -0,0 +1,124 @@
---
name: config-validation
description: Write or change ESPHome configuration validation - CONFIG_SCHEMA, cv.Schema, cv.typed_schema, custom validator functions, config keys and CONF_ constants, renamed or deprecated keys, and the language schema that script/build_language_schema.py extracts from them. Use whenever a change touches a component's schema or a validator in config_validation.py, automation.py or a component's .py files.
---
# Configuration validation
ESPHome validates YAML with `voluptuous` schemas built from `esphome/config_validation.py` (`cv`). The
same schemas are also walked by `script/build_language_schema.py`, which produces the JSON language schema
that editors and the dashboard use for completion and checking. A validation change is only finished when
both still work.
## Writing schemas
- **Type hints:** validators are typed like any other function: `def validate_x(config: ConfigType) ->
ConfigType:`, with `ConfigType` imported from `esphome.types`.
- **One schema per model:** when a component's options depend on a `model` key, use
`cv.typed_schema({...}, key=CONF_MODEL, default_type=...)` with each model's own keys and defaults, not
one schema plus a validator that rejects keys and fills defaults afterwards.
- **Reuse existing validators:** before writing a custom validator, check for an existing one in
`config_validation.py` and compose it in `cv.All(...)` rather than duplicating logic across components.
For example, rename a config key with `cv.rename_key(CONF_OLD, CONF_NEW, removed_in="2026.6.0")`, and
reject mutually-exclusive keys with `cv.has_at_most_one_key(...)` / `cv.has_exactly_one_key(...)`. See
how `api` composes `cv.has_exactly_one_key` + `cv.rename_key`.
- **Common validators:** `cv.int_`, `cv.float_`, `cv.string`, `cv.boolean`, `cv.int_range(min=0,
max=100)`, `cv.positive_int`, `cv.percentage`.
- **Complex validation:** `cv.All(cv.string, cv.Length(min=1, max=50))`, `cv.Any(cv.int_, cv.string)`.
- **Platform-specific:** `cv.only_on(["esp32", "esp8266"])`, `esp32.only_on_variant(...)`,
`cv.only_on_esp32`, `cv.only_on_esp8266`, `cv.only_on_rp2040`.
- **Framework-specific:** `cv.only_with_framework(...)`, `cv.only_with_arduino`. On the ESP32, Arduino is
built as a component of ESP-IDF, so an ESP-IDF API, sdkconfig option or version floor is there on both
frameworks: gate on `esp32.require_idf_version(cv.Version(5, 5, 3), "psram_dma")`, which checks the
platform and the ESP-IDF under either framework, as `spi`, `usb_host` and `wifi` do. Reserve
`cv.only_with_framework("esp-idf")` for a build that has been tried on Arduino and fails there, and write
the actual failure next to it (`sendspin`: arduino-esp32 below ESP-IDF 6.0 bundles a second libsodium,
and from 6.0 sendspin-cpp's enumerators collide with `Arduino.h` macros such as `DISPLAY`).
- **Schema extensions:**
```python
CONFIG_SCHEMA = cv.Schema({ ... })
.extend(cv.COMPONENT_SCHEMA)
.extend(uart.UART_DEVICE_SCHEMA)
.extend(i2c.i2c_device_schema(0x48))
.extend(spi.spi_device_schema(cs_pin_required=True))
```
- **Constants:** `esphome/const.py` is frozen; do not add new `CONF_` constants there. Define a
component-local constant in the component's own `.py`; for a constant shared by multiple components, add
it to `esphome/components/const/__init__.py`. CI (`lint_constants_usage`) fails if the same constant is
defined in three or more component files. Constants used in core files (those not under
`esphome/components`) may be added to `esphome/const.py` but will require adjustment to the CI check.
- **Renamed or removed keys:** see the `breaking-changes` skill for `cv.rename_key` and manual
deprecation warnings.
- **Config-only tests:** schema edge cases and deprecated-syntax migrations go in `validate.*.yaml` test
files (see the `component-tests` skill).
## Schema extraction
`script/build_language_schema.py` sets `esphome.schema_extractors.EnableSchemaExtraction = True` before it
imports any component, then walks every `CONFIG_SCHEMA` (and platform schema) recursively. It understands
`cv.Schema`, `cv.All`, `cv.Any`, dicts of `cv.Required` / `cv.Optional` keys, `.extend()`, `cv.ensure_list`,
`cv.typed_schema`, registries and the known `cv` validators. **A plain function it cannot see into**: a
custom validator that builds or picks a schema at validation time hides every key behind it, and the
dumper silently emits nothing for them. CI only runs the script with `--check`, which does not compare the
output, so a lost schema is not caught.
When a validator function wraps, chooses or builds a schema (rather than checking a single value), make it
visible to the dumper:
1. Decorate it with `@schema_extractor("<type>")` from `esphome.schema_extractors`.
2. At the top of the function, return the data for that type when it is called with `SCHEMA_EXTRACT`
instead of a config value. Compare with `is` (`value is SCHEMA_EXTRACT`); older code uses `==`.
```python
from esphome.schema_extractors import SCHEMA_EXTRACT, schema_extractor
@schema_extractor("schema")
def _outgoing_connection_schema(config: ConfigType | None) -> ConfigType:
if config is SCHEMA_EXTRACT:
return _OUTGOING_CONNECTION_SCHEMA
if config is None:
config = {}
return _OUTGOING_CONNECTION_SCHEMA(config)
```
The type names the dumper accepts, and what `SCHEMA_EXTRACT` must return for each, are in the
`hidden_schemas` branch of `convert()` in `script/build_language_schema.py`. The common ones:
| Type | Return for `SCHEMA_EXTRACT` | Example |
|------|-----------------------------|---------|
| `"schema"` | the schema (or a representative one) to walk | `api` `_outgoing_connection_schema`, `restore_state_schema` in `esphome/core/entity_helpers.py`, `model_schema_extractor` in `esphome/components/mipi/__init__.py` |
| `"enum"` | the dict of options | `sensor_entity_category` in `esphome/components/sensor/__init__.py` |
| `"one_of"` | the list of options | `cv.one_of` |
| `"maybe"` | `(validator, key)` for a scalar shorthand | `cv.maybe_simple_value`, `maybe_conf` in `esphome/automation.py` |
| `"templatable"` | the inner validator | `cv.templatable` |
| `"automation"` | the automation schema | `automation.validate_automation` |
Points to watch:
- The dumper matches the function object by `repr`, so the decorated function must be the exact object
placed in the schema. In a factory that returns a new closure per call, decorate the inner function (as
`restore_state_schema` and `cv.maybe_simple_value` do), not the factory.
- The decorator only records anything when extraction is enabled, and that flag is set before imports, so
the decorator must run at import time (module level or inside a factory called at module level).
- A schema chosen per config value (for example by `model`) has no single answer: return a representative
schema, as `model_schema_extractor` does.
- Plain value checks (`cv.All(cv.string, my_check)`) need nothing: the dumper still sees the surrounding
types and keys.
- `cv.Schema`, `cv.typed_schema`, `cv.ensure_list` and the `cv` helpers are already handled; prefer
composing them over a custom function, which also avoids the extractor work.
### Checking the output
Build the language schema into a scratch directory and look at the component's JSON (it takes about ten
seconds):
```bash
python3 script/build_language_schema.py --output-path /tmp/schema
python3 -c "import json; print(json.dumps(json.load(open('/tmp/schema/my_component.json')), indent=1))" | less
```
Every key a user can write should appear under `config_vars` with a sensible `type`; compare against the
same output from `dev` when changing an existing schema. If the script prints `Unknown extracted schema
type` or raises, the decorator type or the value returned for `SCHEMA_EXTRACT` is wrong. Unit tests for
the dumper live in `tests/script/test_build_language_schema.py`.
.agents/skills/embedded-memory/SKILL.md
+175
View File
@@ -0,0 +1,175 @@
---
name: embedded-memory
description: Choose ESPHome C++ containers and storage that avoid heap use and fragmentation on microcontrollers - std::array, StaticVector with cg.slot_list/SLOT_LIST, FixedVector, std::unique_ptr byte buffers, StringRef, RAMAllocator, and what to avoid (std::vector growth, std::map, std::deque, std::string, new (std::nothrow)). Use when adding or changing C++ members, containers, buffers, strings or registration lists, or when reducing RAM or flash use.
---
# Memory on embedded targets
ESP devices run for months with small heaps shared between Wi-Fi, BLE, LWIP, and application code. Over
time, repeated allocations of different sizes fragment the heap. Failures happen when the largest
contiguous block shrinks, even if total free heap is still large. We have seen field crashes caused by
this.
**Heap allocation after `setup()` should be avoided unless absolutely unavoidable.** Every
allocation/deallocation cycle contributes to fragmentation. ESPHome treats runtime heap allocation as a
long-term reliability bug, not a performance issue. Helpers that hide allocation (`std::string`,
`std::to_string`, string-returning helpers) are being deprecated and replaced with buffer and view based
APIs.
## Container guidelines
1. **Compile-time-known sizes:** use `std::array` instead of `std::vector` when size is known at compile
time.
```cpp
// Bad - generates STL realloc code
std::vector<int> values;
// Good - no dynamic allocation
std::array<int, MAX_VALUES> values;
```
Use `cg.add_define("MAX_VALUES", count)` to set the size from Python configuration.
**For byte buffers:** avoid `std::vector<uint8_t>` unless the buffer needs to grow. Use
`std::unique_ptr<uint8_t[]>` instead. It does **not** provide bounds checking or iterator support like
`std::vector<uint8_t>`; use it only when you do not need these features.
```cpp
// Bad - STL overhead for simple byte buffer
std::vector<uint8_t> buffer;
buffer.resize(256);
// Good - minimal overhead, single allocation
std::unique_ptr<uint8_t[]> buffer = std::make_unique<uint8_t[]>(256);
// Or if size is constant:
std::array<uint8_t, 256> buffer;
```
When the size comes from the config, declare it with `cg.static_buffer()` in `to_code` and pass the pointer
to the constructor, so it lands in BSS (see the `component-codegen` skill).
2. **Compile-time-known fixed sizes with vector-like API:** use `StaticVector` from
`esphome/core/helpers.h` for compile-time fixed size with a `push_back()` interface (no dynamic
allocation).
```cpp
// Bad - generates STL realloc code (_M_realloc_insert)
std::vector<ServiceRecord> services;
services.reserve(5); // Still includes reallocation machinery
// Good - compile-time fixed size, no dynamic allocation
StaticVector<ServiceRecord, MAX_SERVICES> services;
services.push_back(record1);
```
Use `cg.add_define("MAX_SERVICES", count)` to set the size from Python configuration.
**Listener and child-entity registration lists are the most common case, and the most commonly
missed.** When the hub only forwards data to its children and each child's handling is known at build
time, keep no list at all: use `cg.HubFunction` (see the component-codegen skill). When the hub must
store the children (it iterates them for other reasons, or picks fields at run time), a `register_*()`
method called once per child at code generation time has a count that is known at compile time, so it
should never be a `std::vector`. Declare the list with `SLOT_LIST` and register each child through the
call that `cg.slot_list()` returns, passing the hub's `DOMAIN`.
```python
# hub component's __init__.py
register_listener = cg.slot_list(
"MY_COMPONENT_LISTENER_COUNT", "register_listener", DOMAIN
)
# a platform of the hub
async def to_code(config: ConfigType) -> None:
...
hub = await cg.get_variable(config[CONF_MY_COMPONENT_ID])
cg.add(register_listener(hub, var))
```
```cpp
class MyComponent : public Component {
public:
SLOT_LIST(MyComponentListener, listeners_, register_listener, MY_COMPONENT_LISTENER_COUNT)
```
Do not put `#ifdef` around the macro or the loops over the list. Put `#if MY_COMPONENT_LISTENER_COUNT`
only around code that needs a child's own component (its header, its entity type).
If registering does more than append, write the method under `SLOT_LIST_REQUIRES(count)` and store into a
`[[no_unique_address]] SlotList<Entry, count>` member.
If the C++ side adds itself to the list, or the define gates more than the list, use `cg.slot_counter()`
keyed by hub (`_request_slot(str(hub))`) and put the storage behind `#ifdef`.
Request slots from `to_code`, not from a job that runs after `CoroPriority.FINAL`; a late request
raises rather than silently undercounting.
3. **Runtime-known sizes:** use `FixedVector` from `esphome/core/helpers.h` when the size is only known at
runtime initialization.
```cpp
// Bad - generates STL realloc code (_M_realloc_insert)
std::vector<TxtRecord> txt_records;
txt_records.reserve(5); // Still includes reallocation machinery
// Good - runtime size, single allocation, no reallocation machinery
FixedVector<TxtRecord> txt_records;
txt_records.init(record_count); // Initialize with exact size at runtime
```
This eliminates `_M_realloc_insert` and `_M_default_append` template instantiations (200-500 bytes per
instance), needs no upper bound, and is compatible with protobuf code generation when using
`[(fixed_vector) = true]`.
4. **Small datasets (1-16 elements):** use `std::vector` or `std::array` with simple structs instead of
`std::map`/`std::set`/`std::unordered_map`.
```cpp
// Bad - 2KB+ overhead for red-black tree/hash table
std::map<std::string, int> small_lookup;
std::unordered_map<int, std::string> tiny_map;
// Good - simple struct with linear search (std::vector is fine)
struct LookupEntry {
const char *key;
int value;
};
std::vector<LookupEntry> small_lookup = {
{"key1", 10},
{"key2", 20},
{"key3", 30},
};
// Or std::array if size is compile-time constant:
// std::array<LookupEntry, 3> small_lookup = {{ ... }};
```
Linear search on small datasets is often faster than hashing or tree overhead, but this depends on
lookup frequency; in hot paths the O(1) vs O(n) difference may still matter. It is the heavy containers
(`map`, `set`, `unordered_map`) that should be avoided for small datasets unless profiling shows
otherwise.
5. **Strings set once from configuration:** use `StringRef` (`esphome/core/string_ref.h`) rather than
`std::string`. Code generation passes a string literal that lives in flash for the life of the program,
so storing a `std::string` copies it onto the heap for nothing. `StringRef` is a non-owning pointer plus
length; it does not copy, and it must only ever refer to storage that outlives it (a string literal, or
a buffer owned elsewhere).
```cpp
// Bad - heap copy of a literal that is already in flash
void set_keys(std::string keys) { this->keys_ = std::move(keys); }
std::string keys_;
```
```cpp
// Good - no allocation
void set_keys(const char *keys) { this->keys_ = StringRef(keys); }
StringRef keys_;
```
6. **Avoid `std::deque`:** it allocates in 512-byte blocks regardless of element size, guaranteeing at
least 512 bytes of RAM usage immediately. This is a major source of crashes on memory-constrained
devices.
7. **Never use `new (std::nothrow)`:** on ESP-IDF exceptions are disabled, so a failed nothrow allocation
aborts instead of returning `nullptr`. Use `RAMAllocator` from `esphome/core/helpers.h`; CI rejects
`std::nothrow`.
8. **Detection:** look for these patterns in compiler output:
- Large code sections with STL symbols (vector, map, set)
- `alloc`, `realloc`, `dealloc` in symbol names
- `_M_realloc_insert`, `_M_default_append` (vector reallocation)
- Red-black tree code (`rb_tree`, `_Rb_tree`)
- Hash table infrastructure (`unordered_map`, `hash`)
Callback storage (`CallbackManager` vs `LazyCallbackManager`) and templated registration methods are
covered in the `automations` skill.
## Where to spend effort
Prioritize container optimization for core components (API, network, logger), widely used components
(mdns, wifi, ble), and components causing flash size complaints. Avoiding heap allocation after `setup()`
is always required regardless of component type; the priority list is about effort spent on container
migration (e.g. `std::vector` to `StaticVector`).
.agents/skills/hardware-test/SKILL.md
+31 -8
View File
@@ -38,11 +38,15 @@ driven, what the logs show, and the same flow on a `dev` build when a quirk coul
5. **Flash and RAM deltas are measured against the PR's merge base** (`git merge-base origin/dev HEAD`
checked out in a throwaway worktree), with the baseline commit named in the table. When a delta
looks odd, diff symbol sizes (`nm -S -C --size-sort` from the matching toolchain) before quoting it.
When a change moves storage between the heap and static RAM, the static number alone misleads: also log
the free heap at the end of setup (`on_boot` at priority -100) over three boots of each build and report
the total in use (static RAM plus heap used).
6. **Prove a quirk is pre-existing before blaming the PR:** run the identical flow on a `dev` build in
the same session and say so in the results.
7. **Pipe safely.** Set `PYTHONUNBUFFERED=1` on any `esphome run` or `esphome logs` whose output is
piped, or lines land minutes late. Bound every long command with `timeout` (coreutils) or
`perl -e 'alarm shift; exec @ARGV' <seconds> <command>` on macOS without it.
`perl -e 'alarm shift; exec @ARGV' <seconds> <command>` on macOS without it. Save an exit code with `rc=$?`
right after the command: in `echo "$(date +%T) rc=$?"` the command substitution runs first and `$?` reads 0.
## Workflow
@@ -67,9 +71,17 @@ driven, what the logs show, and the same flow on a `dev` build when a quirk coul
automations in the config itself.
7. **Analyze** with `grep -a -c` counts over the capture and keep an `-events.txt` extract of the lines
that matter. Decode crashes with the platform's `addr2line` (see `reference/boards.md`).
8. **Report** on the PR as a table: build SHA, board and framework, what was driven, counts, result,
plus the `dev` control row and the exact flow in a `<details>` block. No credentials, no port names,
no IP addresses.
8. **Report** on the PR. Every result comment starts with this two-line GitHub alert, then a blank line:
```
> [!NOTE]
> Automated testing results
```
Then one short sentence saying what was tested (builds and SHAs, board, what was driven), a results table
(build SHA, board and framework, what was driven, counts, result, plus the `dev` control row), short bullets
for the findings, and the setup and exact flow in a collapsed `<details>` block. Answer any question asked on
the PR directly in the comment. No credentials, SSIDs, IP addresses, port names or other bench details.
## Flashing by chip family
@@ -80,6 +92,7 @@ driven, what the logs show, and the same flow on a `dev` build when a quirk coul
| ESP32-S3, C3, C6, H2 native USB | `esphome upload --device /dev/cu.usbmodem*` | `logger: hardware_uart: USB_SERIAL_JTAG`. The USB console can wedge when the app takes over the console (0 bytes, esptool `No serial data received`); replug, or watch through `esphome logs --device <name>.local` |
| Pico W / Pico 2 W | `esphome upload --device <port>` (1200 baud touch); first flash ever via BOOTSEL and `--device /Volumes/RPI-RP2` or `RP2350` | port re-enumerates after upload: `ports.py --wait 2e8a` then capture |
| BW15 kit (RTL8720CF, rtl87xx) | `~/.platformio/penv/.libretiny/bin/python $SKILL/scripts/flash_rtl87xx_kit.py flash write -d <port> <build>/.pioenvs/<name>/*.uf2`. Plain `esphome upload` and plain ltchiptool time out because opening the port asserts DTR/RTS and holds the chip in reset | `serial_capture.py --released`, never `esphome logs` |
| BW12 and other AmebaZ modules (RTL8710BX, rtl87xx) on a plain USB-UART | `~/.platformio/penv/.libretiny/bin/python -m ltchiptool flash write -B 115200 -b 115200 -t 120 -d <port> <uf2>`, started first, then strap by hand: CEN to GND, TX2 to GND, release CEN, release TX2. Without `-B 115200` the system data read at 1.5 Mbaud fails on CH340s (`Data read error at 0x9000`) and nothing is written. A 1 MB image takes about 80 s. A development board with DTR and RTS wired to CEN and the download pin needs no strap | `serial_capture.py`; a reset pulse does not reach CEN on a plain adapter, so a capture starts mid-run |
| BK7238 / CB3S (bk72xx, RTS on CEN) | `~/.platformio/penv/.libretiny/bin/python $SKILL/scripts/flash_bk72xx.py flash write -d <port> <uf2>` (about 75 s) | logs are on UART2 by default; `logger: hardware_uart: UART1` puts them on the flashing adapter. `serial_capture.py --reset` gives a chip-enable reset; a plain open may or may not reset it, check for the bootloader banner |
| LN882H | ltchiptool forces 1 Mbaud for writes; weak adapters need `LN882H_YM_BAUDRATE` patched to 115200 in the penv's `ln882htool.py`; short BOOT to GND while the tool connects | OTA after the first flash |
| nRF52840 Dongle (PCA10059) | Nordic `nrfutil nrf5sdk-tools dfu usb-serial` on the bootloader port, or `dfu: true` in the config so the 1200 baud touch pin-resets into the bootloader; adafruit-nrfutil is refused | app has two CDC ports, ESPHome log on the second |
@@ -102,6 +115,8 @@ ESP-IDF OTA image: `.esphome/build/<name>/build/firmware.ota.bin`. LibreTiny OTA
and then; retry up to three times.
- `api_button.py HOST KEY list|press NAME [...]`: list a device's template buttons or press them over the API; the
recipes drive their test configs with it.
- `apiconn.py`: `connect(host, tries)` (API connect and login with retries, `API_KEY` from the env) and `log_text()`
(an API log line without ANSI codes), imported by the newer API drivers.
- `wifisave_hammer.sh KIND DUT_PORT DUT_YAML DUT_TREE CLIENT_PORT CLIENT_YAML CLIENT_TREE [SETTLE]`:
the fallback AP plus captive portal hammer end to end (compile, flash, capture, counts) with the
templates below. KIND is `esp`, `pico`, `bw15` or `bk`. It ends with `RESULT PASS` (exit 0),
@@ -114,8 +129,8 @@ Per-topic scripts, each described in the matching `reference/recipes/<component>
(server with prefixed misbehaviour cases, PNG, JPEG, BMP and QOI generators, API drivers, first pass timer), `zwave_proxy/` (checksum verifier, device info), `usb_cdc_acm/`
(host driver, Zephyr driver probe), `rtsp_server/` (protocol client, raw rate reader, measurement set,
API image grab), `cse7766/` (API observer with ping), `zephyr_coredump/` (reader flow, decode with the
Zephyr tools), `libretiny_prefs/` (rtc preference harness header), `libretiny_crash/` (BK72xx crash probe header and
capture decoder), `api_outgoing/` (wake cycle and Wi-Fi drop timing readers), `ld2450/` (zone number driver, loopback harness driver with number and binary sensor states and TX frame summarizer), `api/` (raw plaintext native API client for user defined actions, store_yaml recovery client over Noise or plaintext), `http_request/` (update manifest server, update state driver, request test server, action case driver, concurrency, reboot, update check and OTA drivers, `ota_auth/` OTA request cases with basic auth), `modem/` (button and sensor driver over the plaintext API, also used for the BLE MIDI boards), `dfrobot_sen0395/` (API driver and case runner), `homeassistant_light/` (direct bulb driver, held-report case driver), `usb_audio/` (URL player), `speaker_media_player/` (API player driver, pipeline task case runner), `web_server/` (SSE client, request mix, SSE and HTTPD case runners), `mqtt/` (broker config with TLS, client-certificate and WebSocket listeners, test CA with server and client certificates, transport case runner, flash-and-drive runner, CLI TLS check without a board, MAC suffix runner with per-variant configs for two boards, `shutdown/` shutdown message runner and matcher), `udp/` (datagram recorder, `udp.write` payload checker and case driver), `entity_icons/` (icon and device class readback over the API, MQTT discovery, web_server and dump_config, with a comparer), `uart_sim/` (API driver and flash, capture and drive runner for the simulated UART sensors), `remote_base/` (loopback runner and API log decoder per sent frame).
Zephyr tools), `libretiny_prefs/` (rtc preference harness header), `libretiny_crash/` (BK72xx crash probe header,
capture decoder, RTL8720C ROM dump versus report matcher), `api_outgoing/` (wake cycle and Wi-Fi drop timing readers), `ld2450/` (zone number driver, loopback harness driver with number and binary sensor states and TX frame summarizer, frame stream harness with presence hold and link loss drivers, BT MAC driver), `api/` (raw plaintext native API client for user defined actions, store_yaml recovery client over Noise or plaintext), `http_request/` (update manifest server, update state driver, request test server, action case driver, concurrency, reboot, update check and OTA drivers, `ota_auth/` OTA request cases with basic auth), `modem/` (button and sensor driver over the plaintext API, also used for the BLE MIDI boards), `dfrobot_sen0395/` (API driver and case runner), `homeassistant_light/` (direct bulb driver, held-report case driver), `usb_audio/` (URL player), `speaker_media_player/` (API player driver, pipeline task case runner), `web_server/` (SSE client, request mix, SSE and HTTPD case runners), `mqtt/` (`ha_discovery/`, `disable/`, `retained_burst/` and `reconnect/` runners; broker config with TLS, client-certificate and WebSocket listeners, test CA with server and client certificates, transport case runner, flash-and-drive runner, CLI TLS check without a board, MAC suffix runner with per-variant configs for two boards, `shutdown/` shutdown message runner and matcher), `udp/` (datagram recorder, `udp.write` payload checker and case driver), `entity_icons/` (icon and device class readback over the API, MQTT discovery, web_server and dump_config, with a comparer), `uart_sim/` (API driver and flash, capture and drive runner for the simulated UART sensors), `remote_base/` (loopback runner and API log decoder per sent frame), `xiaomi_ble/` (frame and header generator with the expected counts, injecting, advertising and receiving configs, counter and runner), `ble_terminate/` (proxy and peer configs, connect and disconnect driver, peer disconnect matcher, runner), `i2c_slave/` (D1 mini slave and BK7238 master configs), `wpa3_ap/` (PMF AP with join and leave logging, BK7238 and CB3S DUTs, runner and summary), `wisp_ap/` (WISP upstream with AP buttons, WISP and ALWAYS_ON DUTs, client, runner and per phase summary), `wifi_restart/` (WPA3 mixed WISP upstream, static IP DUTs with syslog, runner and summary), `ota_timing/` (OTA upload timer with deflate, raw and TCP modes, API build check, A/B runner and median summary, `inflate_bench/` on-device inflate benchmark with stream generator, configs and syslog runner), `gpio_hold/` (ISR pin hold self test with ESP32 and S3 configs), `ble_event_inject/` (GAP and GATTC event injector header and proxy package), `light_sleep_wake/` (LEDC wave and edge timer for light sleep wakeup on a C3, external wave generator and per-call edge detail probe for peripheral power-down on the P4), `manual_ip/` (station and AP manual IP configs, DNS probe and runners), `web_handlers/` (late handler, web_server, captive_portal and prometheus variants, web OTA runner), `bk72xx_flash/` (flash readback with retries, per partition diff of two dumps), `ble_server_security/` (secure GATT server and pairing client configs, driver, summary and runner), `prometheus/` (datetime metrics configs and driver), `zephyr_ble_server/` (nRF52 server, looping ESP32 client and UF2 flash and count runner), `ble_adv_triggers/` (advertiser with six raw frames, ESP32 and BK72xx receivers with eleven triggers, runner and checker), `sun/` (longitude sweep package, runner and checker), `sensor_filters/` (every filter shape with a fixed input sequence, per-board packages and runner), `led_driver_sniff/` (SPI slave capture header with selftest, config generator, window comparer and runner), `hub_input_sim/` (keypad, wiegand and rdm6300 simulation on a D1 mini, API log runner), `value_range/` (on_value_range sequence with a restart, runner), `ezo_fake_bus/` (fake EZO I2C bus and step config, runner), `twai_self/` (TWAI self-reception header, on_frame config and counter runner), `ota_automations/` (OTA automation package for both OTA platforms, four case runner, repeated web upload runner and per case summary), `output_button/` (pad edge timer header, button package and runner), `homeassistant_button/` (raw plaintext API client for action calls and wizard inputs, package and runner), `uart_button/` (UART0 loopback package, API driver with TX and RX counts, runner), `interval/` (plain and delayed interval package, timing summary and runner), `smp_udp_ota/` (SMP reset fault injector, OTA runner, per mode result check, MCUboot swap limit, running image check and slot blanking UF2, Thread device config), `ld2420_sim/` (fake LD2420 answering the hub's commands on a UART0 loopback, API state recorder, two-build comparer and runner), `nrf52_tcp_probe/` (TCP and UDP socket probe config, build and log check, API check over Thread), `rs485_frame/` (simulated DLE/STX/ETX bus device, frame and gate cases, runner), `hx711/` (fake HXLine truncated
## Templates in `$SKILL/templates`
@@ -137,8 +152,12 @@ capture decoder), `api_outgoing/` (wake cycle and Wi-Fi drop timing readers), `l
and the directories `store_yaml/` (package with secrets one directory up, per-board files),
`http_request_update/` (manifest URL setter shapes, per-board files), `modem/` (modem only and modem plus
Wi-Fi boot checks), `ble_midi/` (fake BLE MIDI instrument and the client), `http_request_action/` (request
action package with per-board files and an OTA flash variant) `uart_sim/` (simulator header, common package, per-build parts and run files) and `remote_base/` (common
package, transmit script, per-board templates and the ESP8266 software sender).
action package with per-board files and an OTA flash variant), `led_wire/` (DUT config and header that reads the
LED strip pads back with RMT RX and an SPI slave), `uart_sim/` (simulator header, common package, per-build parts and run files) and `remote_base/` (common
package, transmit script, per-board templates and the ESP8266 software sender), `i2c_fake/` (fake I2C device
headers with their test configs, see `fake_i2c.md`).
- `microphone_http_stream/`: base config, fake counter and USB microphone variants and the multi-reader client,
described in `reference/recipes/microphone_http_stream.md`.
## When the PR keeps moving
@@ -166,6 +185,10 @@ comment quotes the exact commits. Fetch `origin dev` before computing a merge ba
- The merge base comes from a freshly fetched `origin/dev`; a stale local `dev` puts dependency bumps into the
PR diff and builds the control from the wrong commit.
- A `.local` name can stop resolving in the middle of a run; keep the address from the boot log and drive by it.
- Never point `framework: source:` at a local `file://` copy of LibreTiny to try a patch: PlatformIO installs it over
the shared `~/.platformio/platforms/libretiny`, so every later build on the machine uses the patched copy. Patch
through the ESPHome side (a linker `-Wl,-wrap,<symbol>` or a define) instead, and if it happened, restore the
directory from a clean copy of the same release.
- `wc -l` pads its count on macOS, so `tail -n +$n0` needs `$((n0+0))` or an arithmetic expansion.
- `api:` reboots a board after 15 min without a client: `reboot_timeout: 0s` on `api:` and `mqtt:` for
soak tests.
.agents/skills/hardware-test/reference/boards.md
+218 -7
View File
@@ -41,6 +41,9 @@ Ports are not listed on purpose: they follow the USB hub port and change on ever
under a different name, sign with `python -m espsecure sign_data --version 2 --keyfile
tests/components/esp32/dummy_signing_key.pem`, upload with `esphome upload --file`. The verifier
refuses unsigned images afterwards, so restore with a signed plain build.
- An ESP32 whose bootloader has no app rollback is protected only by `safe_mode` after a bad OTA. Before sending a
change to such a device that nobody can reach by hand, boot the same code on a devkit first and keep a fallback
image of the merge base built.
## ESP32-S3, C3, C6, H2 with native USB
@@ -49,7 +52,16 @@ Ports are not listed on purpose: they follow the USB hub port and change on ever
`Disabling RNG early entropy source`, then 0 bytes, esptool reports `No serial data received`). Only a
USB replug fixes it. Fallback: `esphome logs --device <name>.local` (API log stream, which drops lines
while Wi-Fi is off).
- The ESP32-P4 before silicon revision 3 is bricked by rev3-only firmware (boot loop at bootloader entry).
- The ESP32-P4 before silicon revision 3 is bricked by rev3-only firmware (boot loop at bootloader entry). The
Waveshare ESP32-P4-WIFI6 rev1.3 board is such pre-rev3 silicon.
- S3, C3 and C6 all enumerate as `303a:1001`; confirm the chip with `esptool --port <port> chip_id` before flashing.
- ESP32-C6 test configs: set `wifi: power_save_mode: none`. With the default light sleep, API commands and state
updates arrived seconds late and a 1.2 s step check failed at random on base and PR alike (esphome#22339).
- An S3 on Arduino with `logger: hardware_uart: USB_CDC` enumerates as TinyUSB CDC (`303a:0009`). If that build
crash loops (a FastLED plus NeoPixelBus build aborts in `check_rmt_legacy_driver_conflict`), esptool cannot catch
the port: hold BOOT, tap RST, keep BOOT held about 2 s, then flash with `--before no-reset`. A plain RTS hard reset
leaves it in the loader on USB JTAG; `--after watchdog-reset` boots the app. Keep Arduino LED tests on the classic
ESP32.
- A board left in the ROM bootloader after an upload (BOOT held, or the USB JTAG reset landing in download mode
again) starts its app without a replug through `esptool --port <port> --after watchdog-reset chip-id`; flash a
minimal Wi-Fi plus API image first when recovering from a crash-looping one.
@@ -64,6 +76,22 @@ Ports are not listed on purpose: they follow the USB hub port and change on ever
joins must wait for `network::is_connected()`.
- Parallel Pico builds race on package extraction after a PlatformIO package wipe; one at a time.
- An RTS pulse from pyserial does not reset the board; reboot with `App.safe_reboot()` or the touch.
- LEAmDNS re-enters `update()` from the receive handler on the Pico too (measured), so an ESP8266-only guard does
not cover it.
- An image with only `ota: platform: web_server`, built from a tree without the fix for uploads of unknown size
(before 2026-10-19), cannot be updated again over the network; see `recipes/ota.md` before flashing one.
- RP2350 `panic()` goes through `_exit()` and `__breakpoint()` to a HardFault, and ESPHome's rp2 crash handler
reboots within about a second (USB back 1 to 2 s after the panic). A panic during component setup therefore
boot-loops before USB CDC ever enumerates, which looks like a dead board: no port and no BOOTSEL drive. Recover
with BOOTSEL held on replug, then flash to the `RP2350` volume. To see the crash, trigger it after boot.
- A Pico 2 W can sample any of its own GPIOs from a spare PIO block (PIO2) at 25 MHz while another peripheral
drives the pin, since PIO reads the pad without taking it. That decodes WS2812-style pulses with no wires or
LEDs. Turn a light on at full brightness before probing, or color correction writes zeros. The sample FIFO
overruns now and then; count only full captures.
- A Pico 2 W also makes a byte-exact fake I2C sensor: a raw RP2350 I2C0 interrupt handler (GP4/GP5) that answers
each RD_REQ with one byte from a 256-byte register file, so any read length works (used for BME280/BMP280 in
esphome#22236). The ESP32-S3 I2C slave v2 driver is not usable for register emulation: answering from a task or
straight from the interrupt both gave shifted multi-byte reads.
## BW15 kit (RTL8720CF, LibreTiny rtl87xx)
@@ -88,6 +116,23 @@ Ports are not listed on purpose: they follow the USB hub port and change on ever
- The AmebaZ2 SDK sets `LWIP_TCPIP_CORE_LOCKING 0`.
- The `rtw_is_adapter_up` bus fault after `Disabling AP` happens on LibreTiny 1.13.0 and 1.14.0 alike
(2 of 4 and 3 of 3 runs in #21531); run at least four rounds per build before blaming a PR for it.
- On a fault the ROM handler (ram_vector_table entries 3 to 7) prints a dump of about 4 KB in 0.4 s and
then spins; only the watchdog resets the chip (10 s after `arch_init`, 1 s once the ESPHome crash
handler re-arms it). `.ram.bss.noinit*` (`.system_restore_data`) survives that reset. The core has no
FPU. For a crash that fires once, guard an `interval` lambda with
`!libretiny::crash_handler_has_data()`. For a handler mode (MSP) fault, point vector 16+11 (SDIOD,
unused) at a trapping function and set bit 11 in NVIC ISER and ISPR (0xE000E100, 0xE000E200).
- OTA slots (esphome#22012): a serial `ltchiptool flash write` fills both OTA1 and OTA2, and the slot flag decides
which one boots (`OTA1 USE` or `OTA2 USE` in the ROM banner). Each OTA writes the other slot, so a test that needs
the OTA1 to OTA2 direction runs two OTAs in a row. On dev before #22111 a deflate OTA into OTA2 corrupted the
image, and the next restart hung at `System_Init1` until a serial reflash.
- If the chip still waits in the ROM after a serial flash, pulse CEN to GND once (TX2 floating) to boot the app.
`expected ACK` failures at random blocks mid-transfer can come from one USB hub port; another port fixed them.
- Its Wi-Fi is slow and drops (esphome#21742): a 300 KB deflate OTA takes 3 to 10 minutes, so give the uploader 30
minutes, not 10.
- Wrong-MD5 OTA test without changing firmware: monkeypatch `espota2.hashlib.md5` so only the image checksum (data
over 64 KB) returns a wrong hexdigest. Give each build its own `name:` and read `device_info().name` after a
restart to see which image booted.
## BK7238, WB3S, CB3S (BK7231N) (LibreTiny bk72xx, CH340, RTS on CEN)
@@ -125,8 +170,62 @@ Ports are not listed on purpose: they follow the USB hub port and change on ever
- The BK7238 bootloader prints `App verify failed! Need to recovery factory firmware.` on every boot with any
build; it is harmless. Even with the right layout an ESP32 client did not see the BK7238 fallback AP on
LibreTiny 1.13.0 or 1.14.0, so the wifisave hammer cannot run on it.
- Moving a BK7231N device (CB3S) that sits on its fallback AP to another network: join the host's Wi-Fi to
`<name>-fallback`, OTA to 192.168.4.1, then rejoin the host's own network. Moving it with `/wifisave` instead can
leave it in the captive portal's BLIND_RETRY state (no scan, `Beacon Timeout` every 46 s) until it reboots, and a
log-only serial adapter cannot reset it. Rejoining may change the host's address; update a syslog target that
points at the old one.
- Callbacks run on the `async_tcp` task and log lines can lose a byte. Wi-Fi connect takes tens of ms;
radio enable 160 to 278 ms, disable about 200 ms.
- OTA install: the BK7238 bootloader installs any complete download whose own CRC passes at the next restart, even
when ESPHome refused the update; an incomplete download fails `rt_ota_part_fw_verify` (`Verify firmware CRC32
... !=`) and the old image stays.
- Power save: on the BK7238, `power_save_mode: light` with LibreTiny 1.14.0 gives ping times of 3 to 6 s because
the BDK sets a listen interval of 30 beacons when `CFG_LOW_VOLTAGE_PS` is 1 (esphome#19491).
## BW12 and other AmebaZ boards (RTL8710BX, LibreTiny rtl87xx)
- On a bare module wired to a plain USB-UART (the bench's BW12), download mode is a hand strap: CEN to
GND, TX2 to GND, release CEN, release TX2. Such an adapter does not drive CEN, so neither ltchiptool nor
`serial_capture.py --reset` can reset the chip. A development board that wires DTR and RTS to CEN and the
download pin enters download mode from the tools, like the BW15 kit; the notes below on baud rates still apply.
- ltchiptool links at 1.5 Mbaud and reads the system data at 0x9000 at that rate before it writes at
115200. A CH340 drops bytes there (`Data read error at 0x9000`, `Timed out waiting for Quiet-Handshake`)
and the run gives up without writing. `-B 115200 -b 115200` moves the link to 115200 first and works.
Start the command with `-t 120` so it is already polling while the board is strapped.
- After a failed run the ROM may sit at another baud rate and no longer link; strap again.
- The device builder frontend's AmebaZ flasher follows ltchiptool (link and system read at 1.5 Mbaud),
so it can hit the same read failure on the same adapters.
- Power the module from the adapter's 5 V pin into its own regulator; the adapter's 3.3 V pin cannot
carry the Wi-Fi transmit peaks.
- Capture with `serial_capture.py --released`. With DTR and RTS asserted on the open port, a software
reboot (`App.safe_reboot()`, the restart button) lands in the ROM downloader (`UARTIMG_Download 2`)
and stays there until CEN is pulsed. After a flash the chip also waits in the ROM until CEN is pulsed.
- A full flash takes 50 to 220 s at 115200. While the board is on Wi-Fi, OTA (port 8892) saves the strap,
but the board's Wi-Fi latency (one to two seconds a ping) can make the upload time out.
- `sdk_silent: none` under `framework:` keeps the Wi-Fi driver's join log (`start auth to`, `auth success,
start assoc`, `association success`, `sta recv deauth reason code(N)`); LibreTiny mutes it during the
connect otherwise. `wifi_get_last_error()` after a failed `WiFi.begin()` gives the SDK's reason
(1 no network, 2 connect failed, 3 handshake failed, 6 auth failed); LibreTiny only logs `ret=-1`.
- Some modules ship with no RF calibration in efuse, only the chip ID and MAC. Dump the logical map with
the ROM's `EFUSE_LogicalMap_Read(buf)` (512 bytes): TX power indexes are at 0x10 to 0x1A, crystal trim
at 0xC9, MAC at 0x11A; 0xFF means the driver uses its default (trim 0x20). Linking with
`-Wl,-wrap,EFUSE_LogicalMap_Read_ACUT` lets a wrapper rewrite blank bytes before the driver parses
the map on each radio start. See `recipes/libretiny.md` for the per-boot trial harness used to A/B them.
- Scan results report WPA2-AES access points as `WPA PSK`: LibreTiny truncates `rtw_security_t` to
`uint8_t` before mapping it. Cosmetic. Open networks come out as `WIFI_AUTH_INVALID` (255) on both
AmebaZ and AmebaZ2, so `auth != WIFI_AUTH_OPEN` marks them encrypted.
- After a BSSID plus channel join, LibreTiny's `set_pscan_channel(ch, false)` leaves the driver with no
channel to scan, so the next SSID only join fails at once (no `start auth`), and the first scan after a BSSID
join comes back empty (no results in about 62 ms on the BW15). A `wifi_set_pscan_chan` list of channels 1 to 13
returns 0 but leaves only the last channel enabled, and re-applying the channel plan does not help either
(AmebaZ2 reports plan 0xFF; AmebaZ's `rtw_set_chplan_cmd` rejects plans above 0x58 except 0x7F). What works
(esphome#21749, BW15): set the one-channel pscan list yourself and pass channel 0, so the join's own scan
rebuilds the full list; setting a placeholder SSID `-` before narrowing (esphome#21754) kept joins as fast as
dev with the first scan full on every boot. Not yet confirmed on AmebaZ.
- A 4-way handshake that never finishes after association is reported as `RTW_WRONG_PASSWORD` on AmebaZ
even with the right password; AmebaZ2 reports a real wrong password as a 4-way handshake timeout.
- The driver also posts a SCAN_DONE (number 0) inside every join, on AmebaZ2 too.
## BW16 kit (RTL8720DN, AmebaD)
@@ -145,6 +244,15 @@ Ports are not listed on purpose: they follow the USB hub port and change on ever
to 115200 (lost on reprovision). Weak 3.3 V from the adapter: feed the module's 5 V pad instead. Short
BOOT to GND while the tool connects. OTA afterwards.
- `USE_WIFI_AP_EXCLUSIVE` (one radio mode at a time) exists only on LN882x; compile-check changes there.
- The ESPHome OTA port on LN882x is 8820, not LibreTiny's 8892 (BK72xx, RTL87xx); helper scripts that hardcode
8892 get `Connection refused`.
- WL2H-U modules with the Tuya flash layout: app at 0x007000 (0x113000 long), OTA at 0x11A000 (0xA8000 long). A
full OTA upload over a slow link takes 2 to 14 minutes.
- UF2 block order differs per family: LN882H puts the device image first and the flasher image after it, BK72xx
puts the flasher image first and the device image last. The LN882H bootloader installs a complete, valid OTA
partition even when the upgrade state is still `UPG_STATE_DOWNLOAD_ING` (esphome#22111).
- Without serial access to recover, never send a corrupted image; wrong-MD5 and cut-upload tests with valid
images are safe.
## nRF52840
@@ -156,9 +264,11 @@ Ports are not listed on purpose: they follow the USB hub port and change on ever
`dfu: true` wires up on this board. A pulsing red LED means bootloader; the side RESET button
re-enters it.
- Makerdiary MDK USB dongle: UF2 bootloader without SoftDevice, app at 0x1000, `UF2BOOT` volume,
adafruit-nrfutil, GPREGRET 0x57 works. RGB LED active low (red P0.23, green P0.22, blue P0.24),
button P0.18.
- Adafruit ItsyBitsy nRF52840 Express (UF2 bootloader with S140, bootloader port `239a:0051` plus an
adafruit-nrfutil, GPREGRET 0x57 works. The running app enumerates as `1915:CAFE` or `239A:0029`. RGB LED
active low (red P0.23, green P0.22, blue P0.24), button P0.18.
- Both boards reflash without a button once they run a `dfu: true` build: `esphome upload --device <any app CDC
port>` on the PCA10059, a 1200 bps open of the log port plus a copy of `zephyr.uf2` to the volume on the ItsyBitsy.
- Adafruit ItsyBitsy nRF52840 Express (UF2 bootloader 0.9.0 with S140 6.1.1, bootloader port `239a:0051` plus an
`ITSY840BOOT` volume): the board DTS already has `cdc_acm_uart0`, so the logger port is the first CDC
port and a `usb_cdc_acm` interface 1 the second. A `dfu: true` build enters the bootloader on the
1200 bps touch (an app without it needs a double tap on RESET); `adafruit-nrfutil` over the bootloader
@@ -172,14 +282,25 @@ Ports are not listed on purpose: they follow the USB hub port and change on ever
the port open, and the logger warns `logger took a long time`. Print one line per `loop()` instead.
- Zephyr settings survive a reflash: key a `restore_value` global by a `run` substitution when a test needs
a never-saved value.
- Thread: nRF52 `openthread:` accepts only `tlv:`; the individual keys (network_key, channel, ...) are rejected at
validation. To list nearby networks with channel and PAN ID, call
`otThreadDiscover(InstanceLock::acquire().get_instance(), 0, 0xFFFF, false, false, cb, nullptr)` from an
`interval:` lambda in an included header; results arrive on the OpenThread thread and log fine.
- A wrong network key on a real network's channel and PAN ID makes the device form its own partition as leader on
that PAN within about 30 s; take it off Thread at once. Never try guessed datasets against a network in use.
## Waveshare ESP32-S3-ETH with the OV5640 camera module
- Native USB console (`303a:1001`), ESP32-S3R8, 16 MB flash, 8 MB octal PSRAM, W5500 on SPI (MOSI 11,
MISO 12, SCLK 13, CS 14, INT 10, RST 9), TF card on 4..7, WS2812 on 21.
- Camera header (vendor schematic): XCLK 3, SIOD 48, SIOC 47, VSYNC 1, HREF 2, PCLK 39, D0..D7 = 41, 45,
46, 42, 40, 38, 15, 18. PWDN is tied to GND and RESET is an RC to 3.3 V on the board, so no reset or
power-down GPIO exists.
- Camera header (vendor schematic): XCLK 3, SIOD 48, SIOC 47, VSYNC 1 (a 0 ohm link to GPIO1, alternative
GPIO16), HREF 2, PCLK 39, D0..D7 = 41, 45, 46, 42, 40, 38, 15, 18. PWDN is tied to GND and RESET is an RC to
3.3 V on the board, so no reset or power-down GPIO exists.
- It can run from PoE and USB-C at once, so the USB-C can move from the host to a USB device for `usb_uart` or USB
host tests while the board stays up; flash and read logs over Ethernet while it is unplugged. In USB host mode
the USB-C is the host port after the first flash: log over the API with `logger: hardware_uart: UART0`.
- A crash-looping image can wedge its USB console until a BOOT replug. Never force allocation failures on it by
hogging RAM: Wi-Fi then aborts in `operator new` or the loop task trips the task watchdog.
- GPIO8 switches the camera 3.3 V rail through a P-channel MOSFET: LOW = camera powered, gate pulled up so
the camera is off by default. `power_down_pin: GPIO8` only pulls it low 10 ms before the probe, which is
not enough; use `switch: gpio GPIO8 restore_mode: ALWAYS_OFF setup_priority: 800` plus `on_boot:
@@ -203,3 +324,93 @@ Ports are not listed on purpose: they follow the USB hub port and change on ever
- `dns-sd -L <name> _meshcop._udp local.` shows the `omr` prefix; it disappears when routing is dead.
Keep one capture per chip; never reset the H2 over USB mid-test unless that is the test (the host
logs `Unexpected RCP reset: RESET_OTHER` and recovers).
## Building against a patched LibreTiny
- Clone LibreTiny at the tag ESPHome pins, commit the patch, and set `framework: version: <tag version>` plus
`source: file://<clone>` under `bk72xx:` or `rtl87xx:`. PlatformIO installs it as
`~/.platformio/platforms/libretiny` (the stock copy is `libretiny@src-<hash>` and is not touched).
- A later commit in the clone is not picked up by the next build; patch the installed copy or remove it. Remove
`~/.platformio/platforms/libretiny` when done.
- BDK headers such as `power_save_pub.h` have no `extern "C"`; wrap them when including them from the Arduino
core's C++ files.
## LibreTiny crash and abort() facts (esphome#21596, #22288)
- `abort()` on dev: the BK7238 hangs for good (the main loop stops and the watchdog never fires once Wi-Fi is up;
recover with an RTS pulse on CEN, `serial_capture.py --reset`). The BW15 (RTL8720CF) restarts with no crash
record. The LN882H reboots only after about 18 s through the watchdog (`WDT Reset`), with no record: the SDK's
`abort()` and `_exit()` (`components/libc/newlib_stub.c`) and its FreeRTOS `configASSERT` are spin loops. With
#22288 all three reboot in 1 to 2 s and log `Reason: Abort`, with the PC at the call site and no `LR:` line.
- `assert()`, `std::terminate` and a failed `new` all reach `abort()` (nano libsupc++). `raise(SIGABRT)` returns,
because `_kill` is a nosys stub.
- `__builtin_trap()` faults on every board. A store to `nullptr` or 0xDEADBEE0 does not fault on the BK7238. On
the BW15 a `nullptr` store does not fault, and loads and stores at 0xDEADBEE0 give only imprecise bus faults
(CFSR 0x400, no BFARVALID), so testing the fault address path needs another Cortex-M chip.
- BK7238 safe mode: each quick crash reboot counts toward it (`Last reset too quick; invoke in N restarts`), so
back-to-back crash tests can drop the board into safe mode.
- LN882H: the previous crash is replayed to every new API log client until the next crash; that is expected, not a
double record. Once, the first `__builtin_trap()` after a fresh OTA took about 12 s to reboot; retries took 2 to
3 s and it did not reproduce.
- `~/.platformio/packages/toolchain-gccarmnoneeabi` can vanish between a build and the decode (it comes back with
the next LibreTiny build). Until then the `arm-none-eabi-addr2line` and objdump of
`toolchain-rp2040-earlephilhower` read any ARM ELF.
- RTL8720C: a noreturn `bl abort` can be the last instruction of a function, so the raw return address points at
padding addr2line cannot place. Decode `(addr & ~1) - 2` to get the call line; #22288 records it that way.
- Abort reports (#21596): early heads put LR 0x00000000 first in the address list; later heads drop a zero LR, so
an abort report starts with the backtrace.
## Waveshare ESP32-C6-GEEK
- Native USB JTAG serial (`303a:1001`), 16 MB flash, 1.14" ST7789 LCD and TF card; the vendor docs give no GPIO
numbers. Pins that read a fixed level against the internal pulls: 1, 2, 7, 20, 23 high, 6 low. Free for pad
tests: 0, 3, 4, 5, 18, 19, 21, 22 (see `recipes/gpio_hold.md`).
## Waveshare ESP32-P4-Module-DEV-KIT (USB host)
- ESP32-P4 rev v1.3, 16 MB flash, console on a CH343 (`1a86:55d3`). Other boards use the same chip for their
console, so check with `esptool chip_id`.
- USB host for `usb_host`: set the Host/Device jumper to HOST and use the bottom USB-A port nearest the Ethernet
jack (the high-speed OTG controller); the other USB-A ports and the USB-C marked "USB" do not reach it. The ports
are unlabelled. The port powers the device.
- ESP-IDF programs the FIFO split only when a device connects: read `GRXFSIZ`, `GNPTXFSIZ` and `HPTXFSIZ` at
`DR_REG_USB2_BASE` + 0x24, 0x28 and 0x100 after enumeration. GHWCFG3 (0x4C, high 16 bits) reads 896 lines. The
default split is RX 512, NPTX 256, PTX 128.
- Not every P4 board has a USB host port; check before planning a `usb_host` test on one.
## Gelidus Research PS1 v2.3 (LD2420 presence sensor)
- ESP32-D0WD-V3 rev 3.1 on a CH340 (`1a86:7523`); `esphome upload --device <port>` works directly.
- LD2420 UART: TX GPIO17, RX GPIO16, 115200 (radar firmware v1.6.1). Status LED GPIO23, night light PWM on GPIO25.
- The vendor package is at github.com/GelidusResearch/grps (`packages/grps-ld2420.yaml`); copy it locally for tests.
- The radar needs a person in its field. Energy frames are `F4 F3 F2 F1 23 00 <presence> <range cm LE16> ...`; a
UART `debug:` block on RX shows them.
## ESP32-C3 Super Mini (native USB, 4 MB XMC flash)
- Shows up as `303a:1001`; confirm with `esptool --port <port> chip_id`. Board `esp32-c3-devkitm-1`,
`logger: hardware_uart: USB_SERIAL_JTAG`. Avoid GPIO2, 8 and 9 (strapping; 8 is the LED, 9 is BOOT).
- A 6-pin BME680 breakout (CS, ADDR/MISO, SCL, SDA, GND, VCC) on SDA GPIO6 and SCL GPIO7 with CS and ADDR left
open answers at 0x77 through the breakout's pull-ups, and the `bme680` platform reads fine.
- BME688 parallel mode never reads in `bme68x_bsec2` on dev: the read timer is re-armed by each 30 ms run before
its 41.6 ms delay ends. Entering parallel mode at all needs gas estimates subscribed at `BSEC_SAMPLE_RATE_SCAN`
and no IAQ outputs.
## mDNS responder tests (#22267)
- When the host's multicast does not reach the device, query its port 5353 directly as legacy unicast (a
python-zeroconf packet sent from a normal UDP socket) to dump records or hammer the responder.
- On a crowded Wi-Fi channel, back-to-back query loss swung from 0 to 14% between builds for no code reason. Judge
responder timing on an Ethernet board.
## nRF54LM20 DK (PCA10184, on-board J-Link)
- The power switch must be ON or nothing enumerates. The ESPHome log (uart20) is on the second J-Link VCOM port;
the first is unused.
- Flash with `esphome upload <yaml> --device JLINK` (sdk-nrf toolchain); the LM20 needs no west `--device` override.
The J-Link re-enumerates after the flash, so start the capture after the port comes back.
- Reset without halting: JLinkExe `-device NRF54LM20A_M33 -if SWD -autoconnect 1` with `w4 0xE000ED0C 0x05FA0004`
(plain `r` and `g` halt and resume, no reboot).
- LED0 P1.22, LED1 P1.25; BUTTON0 P1.26, BUTTON1 P1.09, BUTTON2 P1.08, BUTTON3 P0.05 (active low, pull-up). GPIO
P1 registers at 0x500D8200 (IN +0x00C, PIN_CNF +0x080), P0 at 0x5010A200.
- Binary sensor state changes are not logged at DEBUG; log the states or count `on_press` to see button presses.
.agents/skills/hardware-test/reference/recipes/README.md
+39 -7
View File
@@ -11,20 +11,21 @@ One file per component, named after it:
- [`espnow.md`](espnow.md): ESP8266 broadcast receive
- [`hdmi_cec.md`](hdmi_cec.md): two-board wire
- [`http_request.md`](http_request.md): update manifest URL changed at run time, every setter shape, a swap under a running check, non-blocking request actions with loop gap, queue, cancel and reboot checks, OTA request cases with basic auth and MD5 sources
- [`ld2450.md`](ld2450.md): polygon zones, zone number round trip through the radar's readback, ESP8266 loopback harness without a radar
- [`ld2420.md`](ld2420.md): hub setup and sensor states with a simulated module on a UART0 loopback (energy and simple mode)
- [`ld2450.md`](ld2450.md): polygon zones, zone number round trip through the radar's readback, ESP8266 loopback harness without a radar, presence hold and link loss on a frame stream, BT MAC readback
- [`ld2412.md`](ld2412.md): output pin level through the basic configuration command, held back writes
- [`libretiny.md`](libretiny.md): rtc preference emulation, BK72xx crash report on the next boot
- [`libretiny.md`](libretiny.md): rtc preference emulation, BK72xx and RTL8720C crash report on the next boot with a ROM dump matcher, BK7238 BLE bond store safety with a full flash backup and per partition diff, BK7238 OTA versus the board layout and bootloader
- [`modem.md`](modem.md): PPPoS modem component boot check with no modem attached, loop blocking and disable timing
- [`mqtt.md`](mqtt.md): broker bench, QoS, reconnect, crash log over MQTT, WebSocket transports with a local and a public broker, TLS trust sources (own CA, client certificate, certificate bundle, no verification) with the CLI check, MAC suffix topics and will messages on two boards, shutdown message delivery on restart, disable and deep sleep
- [`nrf52.md`](nrf52.md): dongle board support
- [`nrf52.md`](nrf52.md): dongle board support, zephyr_ble_server connection slot under reordered callbacks, SMP over UDP OTA over Thread with reset faults, MCUboot swap limit and stuck slot recovery, TCP stack probe
- [`online_image.md`](online_image.md): stalled and malformed downloads, PNG, JPEG, BMP and QOI decode time per loop pass with large images and small buffers
- [`openthread.md`](openthread.md): border router on the S3 host plus H2 RCP
- [`ota.md`](ota.md): overlap and lock, timeouts, deflate
- [`ota.md`](ota.md): upload without a configuration and the refusal checks, overlap and lock, timeouts, deflate, upload timing A/B per build and board with deflate and raw, on-device inflate benchmark, OTA automations on two platforms
- [`rtsp_server.md`](rtsp_server.md): camera streaming on the Waveshare ESP32-S3-ETH
- [`scheduler.md`](scheduler.md): loop wake A/B
- [`scheduler.md`](scheduler.md): loop wake A/B, interval startup delay and control from lambdas
- [`udp.md`](udp.md): datagrams, multicast, sockets, `udp.write` payload shapes
- [`usb_cdc_acm.md`](usb_cdc_acm.md): nRF52840 dongle host driver
- [`wifi.md`](wifi.md): reboot_timeout with a fallback AP, DHCP lease cache, Easy Connect (DPP), WISP bridge with an ethernet upstream
- [`wifi.md`](wifi.md): reboot_timeout with a fallback AP, DHCP lease cache, Easy Connect (DPP), WISP bridge with an ethernet upstream, reboots against a WPA2/WPA3 PMF access point, WISP and ALWAYS_ON AP switching, AP restarts with WPA3 mixed and LIGHT power save
- [`zephyr.md`](zephyr.md): preferences on the nRF52840 dongle
- [`zephyr_coredump.md`](zephyr_coredump.md): crash and decode on nRF52 boards
- [`zwave_proxy.md`](zwave_proxy.md): frame checksums on a live proxy
@@ -36,5 +37,36 @@ One file per component, named after it:
- [`web_server.md`](web_server.md): state SSE stress and the HTTPD task stack on web_server_idf, entity icon and device class readback
- [`uart_sim.md`](uart_sim.md): UART sensors simulated on a classic ESP32 with loopback and cross-wired UARTs
- [`gpio_expander.md`](gpio_expander.md): interrupt driven expander inputs, loop idle checks, testing a device out of reach
- [`led_strip.md`](led_strip.md): forcing a failed strip allocation, RMT symbols on the S3
- [`led_strip.md`](led_strip.md): forcing a failed strip allocation, RMT symbols per chip, loop cost per strip
- [`remote_base.md`](remote_base.md): remote_receiver protocol decoding through a one-pin loopback on ESP32 and ESP8266, no IR hardware
- [`xiaomi_ble.md`](xiaomi_ble.md): Xiaomi, ATC and PVVX parsing by injecting scan results into the ESP32 tracker or advertising them from a second ESP32, real AES-CCM frames, duplicate filter model
- [`ble_terminate.md`](ble_terminate.md): proxy disconnect against a peer with peripheral latency
- [`i2c_slave.md`](i2c_slave.md): fake I2C slave on a D1 mini, ESP32 hardware master as the control
- [`fake_i2c.md`](fake_i2c.md): fake I2C devices with no chip: in-firmware buses for many drivers, a Pico 2 W BME280/BMP280 target, a DS2482-800 simulator, NACK injection for vl53l0x
- [`gpio_hold.md`](gpio_hold.md): GPIO hold through the ISR pin API, pad read back with no wiring, per chip pin notes
- [`ble_event_inject.md`](ble_event_inject.md): made up GAP and GATTC events fed into the ESP32 BLE handlers from a button
- [`light_sleep_gpio_wake.md`](light_sleep_gpio_wake.md): GPIO wakeup from auto light sleep with an LEDC wave that keeps running in sleep, and with an external wave and peripheral power-down on the ESP32-P4
- [`manual_ip_and_web_handlers.md`](manual_ip_and_web_handlers.md): station, AP and Ethernet manual IP, web handlers added late and web OTA with web_server, captive_portal or prometheus
- [`ble_server_security.md`](ble_server_security.md): esp32_ble_server pairing, encrypted and MITM characteristics, subscription before and after pairing, bond reuse per ESP-IDF version
- [`prometheus.md`](prometheus.md): date, time and datetime metrics in UTC and another time zone
- [`ble_adv_triggers.md`](ble_adv_triggers.md): BLE service and manufacturer data advertise triggers over the air on the ESP32 and BK72xx trackers, with a second ESP32 advertising known frames
- [`sun.md`](sun.md): on_sunrise and on_sunset by sweeping the observer's longitude, one full sweep in about 17 minutes
- [`sensor_filters.md`](sensor_filters.md): every sensor, binary_sensor and text_sensor filter shape fed a fixed input sequence, outputs compared bit for bit between builds
- [`led_driver_sniff.md`](led_driver_sniff.md): bit-banged LED drivers captured on the ESP32's own pads with SPI slaves through the GPIO matrix, no chips
- [`hub_input_sim.md`](hub_input_sim.md): matrix_keypad, wiegand, rdm6300 and key_collector driven from a D1 mini's own pins and UART loopback
- [`value_range.md`](value_range.md): sensor and number on_value_range with a fixed sequence and a restart
- [`ezo_fake_bus.md`](ezo_fake_bus.md): the ezo component against a fake I2C bus that answers like an EZO circuit
- [`twai_self.md`](twai_self.md): esp32_can on_frame with the controller hearing its own transmit pad, no transceiver
- [`buttons.md`](buttons.md): output button pad timing, homeassistant button through a raw API client with the wizard input, uart button on the UART0 loopback
- [`rs485_frame.md`](rs485_frame.md): DLE/STX/ETX bus on an ESP32-C3 with a cross-wired simulated bus device (frame cases, gate timing)
- [`hx711.md`](hx711.md): fake HX711 driven from the other core, every published value matched to the served conversion
- [`automation_trace.md`](automation_trace.md): automation codegen A/B, a marker trace of chains, conditions, loops and script modes over the API
- [`bluetooth_proxy.md`](bluetooth_proxy.md): held GATT link after a half-open API session, frozen Home Assistant stand-in
- [`crash_report.md`](crash_report.md): crash buttons, fetching the previous boot's crash report over the API, per-chip abort facts
- [`https_idf.md`](https_idf.md): web_server_idf HTTPS test component, listener switch, stalled TLS clients, bad key
- [`mdns.md`](mdns.md): legacy unicast mDNS dump, hammer and latency straight to the device
- [`sim_buses.md`](sim_buses.md): PCF8574/HD44780, MAX7219, SPI spy, packet_interface and SN74HC165 simulators, status LED probe, fake Home Assistant, cg.static_buffer probes
- [`sigma_delta.md`](sigma_delta.md): pulse density of the sigma_delta speaker pin read inside the ESP32-P4, rtttl note onset and release
- [`microphone_http_stream.md`](microphone_http_stream.md): raw PCM over HTTP with a counter fake mic or a USB mic, multi-reader client
- [`i2s_audio.md`](i2s_audio.md): I2S microphone fed by an I2S TX channel on the same S3 through three jumpers
- [`voice_assistant.md`](voice_assistant.md): late TTS start on the Voice PE with a slow announcement URL
.agents/skills/hardware-test/reference/recipes/automation_trace.md
+24
View File
@@ -0,0 +1,24 @@
# Automation code generation A/B (#21978 to #21980)
A change to how actions, conditions or scripts are generated must not change what runs or in which order.
`scripts/automation_trace/automation-trace-common.yaml` (a package) logs a marker `M <case> <values>` at every step.
It covers:
- merged action chains, delays inside chains, nested `if`/`else` with and/or/not/xor, `choose` with `else`;
- `while` with and without a delay, nested and dynamic `repeat`, `wait_until` and `for:`;
- `single`, `restart`, `queued` and `parallel` scripts with parameters, a self `script.stop` mid-chain;
- `on_value_range`, alarm panel triggers, and parallel scripts with `max_runs` 2, 3 and 4 that execute themselves
from an `if` branch.
`run.sh LABEL` writes the per-run file (board, Wi-Fi from `secrets.yaml`, the package), builds and flashes over
`PORT`, takes the device address from the serial log and runs `drive.py HOST OUT`. The driver records the boot run,
a "Run All" press and API-driven triggers (Chain Button twice, Num 70 and 20, Sw on and off, Sel c and a). The
runner keeps the part from `DRIVER press Run All` on in `out-at<LABEL>.trace`; diff dev against each PR head. The
boot run is partly missed while the API connects, so it is left out of the diff.
- Pass: the Run All pass reaches `M done`, no `SHOULD_NOT_RUN` or `NOT_REACHED` marker appears, and the trace is the
same on both builds.
- The interleaving of the `queued` and `parallel` scripts with later steps is timing dependent, but it was identical
across builds and runs.
- To check a real device config as well, OTA the PR build and toggle one light and one switch from an API client,
returning each to its original state, and compare states and logs with the base build. Get the owner's approval
before flashing a device that is in use.
.agents/skills/hardware-test/reference/recipes/ble_adv_triggers.md
+28
View File
@@ -0,0 +1,28 @@
# BLE service and manufacturer data advertise triggers (#21822, #21823, #21827)
`scripts/ble_adv_triggers` checks `on_ble_service_data_advertise` and `on_ble_manufacturer_data_advertise` over the
air on the ESP32 and BK72xx trackers.
- Advertiser: `advtrig.yaml` on any second ESP32 with BLE. Every 250 ms it switches to the next of six raw
non-connectable advertisements (`adv_frames.hpp`, random static addresses `C4:C1:38:00:00:21` to `26`):
| Address | Contents |
|---|---|
| `...:21` | service data 181C `AA01` and manufacturer data 02E5 `BB01` |
| `...:22` | service data 32-bit 12345678 `AA02` |
| `...:23` | service data 128-bit 12345678-9ABC-DEF0-1122-334455667788 (wire order) `AA03` |
| `...:24` | manufacturer data 181C `BB04` (the service UUID of `...:21`, other data kind) |
| `...:25` | two service data 181C entries, `AA05` then `AA06` (only the first may fire) |
| `...:26` | the 128-bit UUID in printed byte order, `AA07` (must not match) |
- Receivers: `rx-esp32.yaml` (classic ESP32, passive scan) and `rx-bk72xx.yaml` include the same eleven triggers
(`triggers.yaml`). `rx.hpp` counts each trigger's hits by payload (`AAnn`, `BBnn`, anything else as `other`) and
logs the table every 20 s, plus all adverts and those from the advertiser.
- `run.sh esp32|bk72xx LABEL` builds, flashes, captures 150 s and runs `check.py`, which prints PASS or FAIL. Run it
once per build (dev merge base and each PR head). About 550 hits per trigger on ESP32 and 170 on a BK7238 in that
time.
- `mac_address: 00:00:00:00:00:00` meant no filter on the ESP32 tracker before #21823 and filters on that address
after it (BK72xx always filtered). Pass `ZERO_MAC=any` for an ESP32 build from before #21823.
- BK7238: with no `wifi:` in the config the tracker logs `Scan started` but receives nothing at all, on dev too. The
BK config therefore joins Wi-Fi.
- Results: https://github.com/esphome/esphome/pull/21827#issuecomment-6489703755
.agents/skills/hardware-test/reference/recipes/ble_event_inject.md
+30
View File
@@ -0,0 +1,30 @@
# Injecting BLE GAP and GATTC events (#21698)
Some BLE paths (repeated connection parameter update failures, a disconnect in the middle of them) are hard to get
from a real peer on demand. `scripts/ble_event_inject` feeds made up events straight into the ESP32 BLE handlers.
- `ESP32BLE::gap_event_handler` and `gattc_event_handler` are protected statics and the class is `final`.
`cp_inject.hpp` reaches them through explicit template instantiation, where access checks do not apply. Its
`cpinject::run()` sends six labelled steps (`STEP1` to `STEP6`): four peers failing five times each, a success
followed by more failures, and disconnects between failures.
- `cp-inject.yaml` is a package for a copy of a proxy config: it adds the include, a VERBOSE logger with the busy
tags back at DEBUG, and an `Inject conn param events` button. Press it with `scripts/api_button.py` while a
log capture (`esphome logs ... --device <ip>` under `timeout`) runs, then count the warning and verbose lines per
step on the PR and on dev.
- The handlers push into a queue and event pool that take a single writer, normally the Bluetooth task. Injecting
from the main task while real events arrive can corrupt them, so the button stops the scan, waits for it to end,
injects and starts it again. Run it with no active proxy connections (no Home Assistant BLE client holding one).
- Fake disconnects use `gattc_if` 0xFE: every client and proxy connection filters on its own `gattc_if_`, so the
queued event reaches only the shared handler. Do not use 0xFF (`ESP_GATT_IF_NONE`), which every client accepts.
- The fake peers (`C0:FF:EE:00:00:0n`) are never connected, so a live proxy keeps serving its real connections;
put it back on its own config afterwards.
## ThermoPro advertisements as scan results (#22047, #22054)
`scripts/ble_event_inject/tpinject.hpp` holds the advertisement records from the `thermopro_ble` unit tests (TP357,
TP357S, TP393, TP960R, TP970R, TP972S, TP25, plus invalid and 13 byte probe frames) and `tpinject::inject_all()`
feeds each one to `global_esp32_ble_tracker->gap_scan_event_handler()` with the device name and the manufacturer
data, the way `scripts/xiaomi_ble` does. Frame N comes from `A4:C1:38:00:10:0N` (up to `:10`), so give each
`thermopro_ble` sensor that MAC, include the header and call `tpinject::inject_all();` from an `interval:` or a
template button. Compare the published states (or the sensor DEBUG lines) on the PR and on dev; no ThermoPro
device is needed.
.agents/skills/hardware-test/reference/recipes/ble_server_security.md
+67
View File
@@ -0,0 +1,67 @@
# esp32_ble_server pairing and encrypted characteristics (#17562)
`scripts/ble_server_security`: a classic ESP32 devkit runs the secure GATT server (`server.yaml`) and a second ESP32
(an S3 here) runs `ble_client` as the central (`client.yaml`). The server has a `read_encrypt` battery level
(`99.9`), a plain characteristic, a `write_encrypt` characteristic that logs what it receives, a `read_encrypt_mitm`
characteristic and a `read_encrypt` characteristic that notifies every 2 s. `run.sh TAG IO AUTH` builds both with the
pairing mode as substitutions, pairs once, reconnects twice, and `summary.py` prints PASS or FAIL. The server needs
`esp32_ble_server` security from #17562 or later: point `SERVER_TREE` at that checkout (the client builds from
`TREE`, dev is fine). `summary.py` needs each refused read to show an `Error reading char` reply, so a run where the
client never connected fails instead of passing.
- `ble_client` never starts pairing on its own (a phone does, after an `insufficient authentication` reply); the
client's `Pair` button calls `BLEClientBase::pair()`. Read errors show as `Error reading char at handle N, status=5`
(not authenticated: no bond) or `status=15` (not encrypted: bond known, link not encrypted yet).
- The `ble_client` text sensor subscribes once, at connect, before any pairing, so a protected characteristic refuses
it. The `Subscribe` button writes the CCCD again after pairing; `ble_client` drops its service list after discovery,
so it writes the characteristic handle + 1 (where ESP-IDF's GATT server puts the CCCD).
- Numeric comparison (`display_yes_no` with `sc_mitm_bond`) tells a fresh pairing from a bond reuse: the
`numeric comparison` line only appears on a fresh pairing. Just Works cannot show it.
- ESP-IDF 5.5.6 drops the bond on the second disconnect on both roles (`Deleting unpaired device`), so that reconnect
pairs from scratch; 5.5.5 keeps it (`-s idf 5.5.5`).
- The server keeps its bonds in NVS. One holding an authenticated bond for the client refuses a Just Works re-pairing
silently; erase the devkit's flash before switching from nc to jw.
- `summary.py` failed both modes at 58636914ab: `read_encrypt_mitm` was readable with no pairing, because
`BLEService::create_characteristic()` took an 8 bit `esp_gatt_char_prop_t` and dropped the MITM bits (1 << 8 and
1 << 9). Check the generated `create_characteristic` call and the property type when a flag above bit 7 is added.
## ESP32 central against the secure server (#17562, #22081)
`scripts/ble_server_security/esp32central-*` swaps the roles: an ESP32-S3 runs the secure server
(`esp32central-srv.yaml`: plain, encrypted, MITM read and write, and an encrypted notify characteristic, numeric
comparison accepted automatically) and a classic ESP32 devkit runs `esp32central-cli.yaml` (`ble_client` with
`display_yes_no` and `sc_mitm_bond`, text sensors that log every value, a MITM write and a link cycle every 40 s).
`bonds.hpp` logs the bond list Bluedroid loaded from NVS on both boards.
- The server never starts pairing (a peripheral only answers a security request), and `ble_client` does not start
it on an insufficient authentication reply (status 5) the way Android does. The client's `on_connect` calls
`esp_ble_set_encryption(remote_bda, ESP_BLE_SEC_ENCRYPT_MITM)` instead.
- `esp32central-flow.sh TAG` erases both boards, flashes them, captures a fresh pairing with three link cycles
(phase A), then resets both together so each loads its bond (phase B), and prints per phase the connects, numeric
comparisons (a fresh pairing), MITM reads, server writes and `Deleting unpaired device` lines. It passes when
phase B reads the MITM characteristic with no numeric comparison and no `Deleting unpaired device` line.
- On ESP-IDF 5.5.6 every other reconnect pairs again (`Deleting unpaired device` on the disconnect after a bonded
reconnect), the regression #22081 describes.
## Bluedroid hex parsing bench (#22081)
`scripts/bluedroid_hex_bench/`: `hexbench.hpp` times Bluedroid's `sscanf` parsing (`string_to_bdaddr` and the
`btc_config_get_bin` loop) against the parsers in #22081's `esp32_ble/bluedroid_hex.h` on the same inputs, valid and
invalid, and checks that the outputs match. `run.sh LABEL` (env `TREE`, `PORT`, `SC`, `PY`, `BOARD`) builds
`bench.yaml`, flashes, captures 25 s and fails on any mismatch or a missing `DONE`. Classic ESP32: about 7 to 9 times
faster for addresses, 6 to 7 times for 16 and 28 byte keys.
## ble_client on_notify with a real server (#21821)
`scripts/ble_notify/`: `server.yaml` (ESP32-S3 GATT server; a numeric and a text characteristic notify every 2 s,
with uint16 frame and empty notification rounds, set through `id(c)->set_value(...)` and `notify()` in a lambda) and
`client.yaml` (classic ESP32 client with two `on_notify` triggers per sensor, one of them delayed, and a link cycle
every 60 s). `run.sh LABEL` (env `TREE`, `SERVER_PORT`, `CLIENT_PORT`, `SERVER_BLE_MAC`, `SC`, `PY`) flashes both,
captures the client 150 s and counts `on_notify` against `on_value` per sensor.
- `run.sh` also requires `All clients established, services released`: before #21821 it never appears with a text
sensor `on_notify`. The delayed txt `on_notify` may miss only the last notify of the capture.
- The server takes one connection. Park any other client that would connect to it with
`esptool --after no-reset chip_id` (the board stays in the bootloader).
- An ESP32-C6 devkit whose native USB port refuses esptool can be flashed and logged through its UART bridge port
with `logger: hardware_uart: UART0`.
.agents/skills/hardware-test/reference/recipes/ble_terminate.md
+27
View File
@@ -0,0 +1,27 @@
# BLE terminate with peripheral latency (#20232)
`scripts/ble_terminate`: an ESP32-S3 `bluetooth_proxy` (active) over Ethernet as the central (`btproxy.yaml`) and a
classic devkit `esp32_ble_server` peer (`btpeer.yaml`). The peer asks for 50 ms / latency 10 / 6 s with
`esp_ble_gap_update_conn_params` 4 s after connect; earlier requests are overwritten by the proxy's own "medium
conn params" after service discovery. Read the proxy's `Conn params updated` line (VERBOSE, API logs) to confirm;
the peer side never logs the event. The proxy only connects to a device its scanner has seen, so `btdrive.py`
subscribes to raw advertisements first.
Measure the peer's own disconnect (`serial_capture.py --ms`) after the client's disconnect: about 0.2 to 0.8 s when
the terminate arrived, about 6 s (the supervision timeout) when it was lost. The client side disconnect time is the
API reply and says nothing. On dev the S3 lost 6 of 12; the PR lost 0 of 16.
`run.sh LABEL ROUNDS` writes `central_bda.hpp` from `PROXY_BT_MAC`, builds and flashes both boards, runs the rounds
and `an.py`, which prints PASS only when every round completed, every peer disconnect came within 3 s and the last
parameter update the proxy logged before each disconnect had latency=10 (a round without it did not test peripheral
latency and counts as inconclusive).
Controller build check: ESP-IDF 5.5.6 ships `libbtdm_app.a` byte for byte the same as 5.5.5 for esp32c3 and esp32s3
(build 51d9dfd). Without hardware:
```bash
strings -a <idf>/components/bt/controller/lib_esp32c3_family/<chip>/libbtdm_app.a | grep -E '^[0-9a-f]{7}$'
```
On a board: a button lambda logging `btdm_controller_get_compile_version()` (declared `extern "C"`) over the API,
since the ESP-IDF init line only reaches the UART.
.agents/skills/hardware-test/reference/recipes/bluetooth_proxy.md
+28
View File
@@ -0,0 +1,28 @@
# bluetooth_proxy
## Held GATT link after a half-open API session (#21256, #22077)
When Home Assistant stops answering without closing its socket, the proxy must not keep the BLE link it opened for
that session. `scripts/bluetooth_proxy_half_open/` reproduces it with:
- `proxy.yaml`: the proxy under test on a classic ESP32 devkit (ESP-IDF, VERBOSE logger with the busy tags at DEBUG,
encrypted API). Build it from the tree under test with a `secrets.yaml` (`wifi_ssid`, `wifi_password`, `api_key`).
- `peripheral.yaml`: a second ESP32 (an S3 here) as a peripheral that only advertises while nobody is connected
(`esp32_ble_server` takes one client by default), with manufacturer data `FF FF 21 56` so the client can find it.
- `ha.py`: the Home Assistant stand-in (aioesphomeapi, `client_info` "Home Assistant test"). Roles: `owner` connects
to the peripheral through the proxy and idles, `observe` counts the peripheral's adverts and the slot report and can
ask for a connect at the end, `swap` connects at once and retries on the first advert. Every role stays subscribed
to advertisements: with no subscriber the proxy's loop disconnects every link at once, which hides the bug (an
early run failed with `disconnect while backend idle` for that reason).
`cases.sh PROXY_HOST LABEL` (env `PROXY_PORT`, `PERI_PORT`, `SC`, `PY`, `API_KEY`) captures both boards and runs
case C (old client killed, new client after 4 s), case H (old client frozen with `SIGSTOP`, so the socket stays open
with no FIN; new client after 4 s, watched 300 s, then it asks to connect and releases) and case N (frozen and nobody
reconnects for 200 s). `cases.sh PROXY_HOST LABEL swap` instead repeats H three times with the new client
connecting at once (`ha.py ... swap ADDR`) and retrying on the first advert. Both end with PASS or FAIL: the cases
fail when an observer exits non-zero, never sees the peripheral advertise (the held link) or the proxy resets, and
swap fails when a round never connects. An owner that never got the link also fails (a rig problem, not a result).
- The proxy drops a frozen session as unresponsive after about 144 s.
- Before #22077, case H holds the link for good: 0 adverts, and the address stays in the slot report. With #22077 the
link is released in the same millisecond as the `replaces` warning. In case 4 the first request logs `Connection
request ignored, state: DISCONNECTING` (connected=false at 0.2 s) and the retry connects at 0.5 to 0.7 s.
.agents/skills/hardware-test/reference/recipes/buttons.md
+46
View File
@@ -0,0 +1,46 @@
# buttons
Button platforms converted to `button::ApplyButton` change no behaviour on the wire, so each test compares what a
press does on dev and on the PR: the pad, the action call or the bytes sent. All three run on a D1 mini with no
wiring and no other device.
## output button pad timing (#21907)
`scripts/output_button`: two `gpio` outputs on GPIO5 and GPIO4 and three output buttons (500 ms and 1000 ms on
GPIO5, 200 ms on GPIO4). `edges.hpp` attaches a CHANGE interrupt to each output pad and stamps every edge with
`micros()`; on ESP8266 a pad reads back its own output level. A script runs four cases three times: one press, a second
press 250 ms in (the reset restarts, high 750 ms), both outputs at once, and the 1000 ms button then the 500 ms
button on the same output 300 ms later (low at 800 ms). `run.sh LABEL` flashes, captures 45 s and prints the edge
lines; diff dev against the PR. Each button keeps its own reset timer, so the 1000 ms button's reset fires later on a
pad that is already low and shows no edge.
Results: https://github.com/esphome/esphome/pull/21907#issuecomment-6516597178
## homeassistant button through a raw API client (#21908)
`scripts/homeassistant_button/ha-button-common.yaml` has three `homeassistant` buttons: `button.doorbell`,
`input_button.chime`, and one with no `entity_id` that is an `api: wizard:` input. An `on_boot` press runs before
any client connects. `habdrive.py HOST` is a plaintext API client that subscribes to Home Assistant actions, presses
each button and prints every action call (service and data). It sets the wizard input with `WizardInputSetRequest`
(message 158, key = FNV-1 hash of the input's id), first to an `input_button`, then to a `button`, then to an invalid
value the device must reject. `run.sh LABEL` flashes, captures and drives it. Expect `button.press` or
`input_button.press` per entity, `No entity ID set yet` and no call before the wizard input is set, and `No clients
connected` from the boot press.
- `homeassistant` entities are internal by default, so the client sees no buttons unless they set `internal: false`.
- Wait for each reply type instead of a fixed time: the hello reply can take more than a second, and a fixed wait
shifts every later reply by one step.
- Results: https://github.com/esphome/esphome/pull/21908#issuecomment-6516693220
## uart button on the UART0 loopback (#21906)
`scripts/uart_button/uart-button-common.yaml` puts four uart buttons on UART0 of a D1 mini: a 10 byte string, five
raw bytes with `0x00` and `0xFF`, the same string again (shares one generated function on the PR), and 64 bytes. It
sets the UART0 loopback bit in `on_boot`, so every press comes back on RX, and `uart: debug: direction: BOTH` logs
both sides. `run.sh LABEL HOST` flashes by USB and runs `ubdrive.py`, which presses each button 3 times over the API
and saves the log. Every `>>>` line must equal the configured payload and its `<<<` line.
- Set the loopback bit at `on_boot` priority -100. At 800 the UART setup runs afterwards and clears it.
- Nothing else reads the bus, so the debugger needs `dummy_receiver: true` to log RX.
- UART0 is the bus, so `logger: baud_rate: 0` and logs go over the API. The device address comes from DHCP or mDNS.
- An RX line sometimes lands after the next press marker when the log stream lags. That is not a byte difference.
- Results: https://github.com/esphome/esphome/pull/21906#issuecomment-6516762337
.agents/skills/hardware-test/reference/recipes/crash_report.md
+26
View File
@@ -0,0 +1,26 @@
# Crash report over the API (#21596, #22288)
#21596 lets an API client fetch the crash recorded on the previous boot; #22288 records `abort()` as a crash on
LibreTiny. `scripts/crash_report/crash-common.yaml` (a package: Wi-Fi from `secrets.yaml`, plaintext API, OTA,
DEBUG logger) adds three buttons: `crash abort`, `crash null store` and `crash div zero`. The per-run file supplies
the board and the name. Flash it, then run the drivers (they import `scripts/apiconn.py`, so run them in place or
put `scripts/` on `PYTHONPATH`):
- `drive.py HOST BUTTON_OBJECT_ID` (for example `crash_abort`) reads the capability, presses the button, reconnects
after the reboot and fetches the report twice (reason, PC, cause, fault address, build time, per-core backtrace),
subscribes to logs with `dump_config` to see what is replayed, and checks the capability from a second client.
It reads an earlier report first, so a stale one cannot pass. It exits 1 when the device still answers after the
press, does not offer a report after the crash, or the report has no reason or a PC of 0.
- `peek.py HOST` prints only the capability and how many replayed `CRASH DETECTED` lines a new log client gets. To
only press a button, use `scripts/api_button.py HOST - press "crash abort"`.
- Decode the PC and the backtrace with the build's ELF (`addr2line -e firmware.elf`). On RTL8720C a noreturn
`bl abort` can be the last instruction of a function, so the return address points at padding: decode
`(addr & ~1) - 2` to get the call line.
- `__builtin_trap()` faults on every board. A store to `nullptr` does not fault on every chip (BK7238 and RTL8720C
ignore it), so the `crash null store` button proves nothing there.
- With #22288, `abort()` reboots BK7238, RTL8720C and LN882H boards in 1 to 2 s and logs `Reason: Abort` with the PC
at the call site. Before it, the BK7238 hangs until reset, the RTL8720C restarts with no record and the LN882H
waits about 18 s for its watchdog.
- Quick crash reboots count toward BK72xx safe mode, so space out back-to-back crash tests on those boards.
- A device that keeps the previous crash replays it to every new log client until the next crash; that is one
record, not two.
.agents/skills/hardware-test/reference/recipes/ezo_fake_bus.md
+37
View File
@@ -0,0 +1,37 @@
# EZO circuits without hardware: a fake I2C bus (#21840)
`scripts/ezo_fake_bus`: the real `ezo` component runs on a classic ESP32, but an `on_boot` priority 900 lambda calls
`id(ph).set_i2c_bus(&fakeezo::bus)`. `fake_ezo.hpp` is an `i2c::I2CBus` subclass that answers like an EZO pH circuit
and logs every write and read with the ms since the command: `R`, `i`, `Slope,?`, `Cal,?`, `T,?`, `L,?`, `Name,?`,
and test replies `pend` (254 twice), `bad` (2), `nodata` (255), `nak` (read NACK) and `full31` (32 bytes with no
terminator), and `sNN` (an NN-character reply, terminated when the read has room). `ezo.yaml` runs the steps:
command bursts larger than the queue, custom commands, calibration, LED, sleep and address changes, and the error
replies.
- The same trick works for any I2C device whose driver only needs write and read: swap the bus pointer, no wiring.
A real `i2c:` block is still needed so the config validates.
- `run.sh LABEL` builds, flashes, captures 90 s and writes `out-ezo<LABEL>.events`. Compare dev and the PR: the
replies, callback texts, read values and the wait before each read (912 ms for reads and calibration, 304 ms for
the rest) must match; differences in queue limits are the PR's intended change.
- Call plain `millis()` in a fake: Arduino builds define a `millis()` macro (`esphome::millis()`), so
`esphome::millis()` breaks there, and on ESP-IDF the plain name resolves through `using namespace esphome`.
- Found with it: dev read past its 32-byte buffer on an unterminated reply (a custom callback got 56 bytes), and
two queued address changes both went to the first new address.
- Results: https://github.com/esphome/esphome/pull/21840#issuecomment-6493565259
## Trigger argument lifetime (StringRef or an owning copy, #22204)
Give each text trigger two automations (`- then:` list items): a synchronous one that logs `x`, `x.size()` and
`strlen(x.c_str())` and hands `x` to a parallel `script` (`text: !lambda return x;`, the script delays 2.5 s), and
one with `delay: 3s` or `wait_until` that logs `x` afterwards. Fire bursts so newer replies reuse the reply buffer
during the wait, then diff the synchronous texts, in order, against the delayed and script texts. Check the generated
`main.cpp` for `StringRef` or `TriggerForwarder<std::string>`. The fake's `sNN` replies give texts of any length.
## A real EZO circuit
An EZO-HUM ships in UART mode (blinking green, streams `33.91\r` every second at 9600 baud). To switch it to I2C
without bridging PGND, flash a one-shot software UART build (TX to the EZO RX, RX from the EZO TX) that writes
`I2C,111\r`; the LED turns blue and the circuit answers at 0x6F. Replies: `i` gives `HUM,1.01`, `Status`
`?STATUS,S,3.31`, `O,?` `?O,HUM,T,DEW`, and `R` with all outputs `34.82,22.03,Dew,5.85`; `Name,x` returns no text.
EZO-HUM rejects `T,?`, `Slope,?` and `Cal,?` (syntax error), so `on_t`, `on_slope` and `on_calibration` need another
circuit or the fake bus. Log every callback with an `EV` prefix and count them per step.
.agents/skills/hardware-test/reference/recipes/fake_i2c.md
+153
View File
@@ -0,0 +1,153 @@
# Fake I2C devices without a chip
## Fake devices on an in-firmware I2C bus
When there is no chip and no wiring, subclass `i2c::I2CBus` in an include, implement `write_readv()` only, answer
the registers the driver reads and check each write. Point the component at it from an `on_boot` lambda that runs
before the component's `setup()`: `id(x)->set_i2c_bus(&fake::bus)` at priority 950, which is ahead of every I2C
component (hubs set up at IO, 900, sensors at DATA, 600). The configs here that use 700 to 1000 work for their
components; use 950 for a new one. Keep a real `i2c:` block in the config so validation passes. Bulk
loops in a button lambda must call `App.feed_wdt()` and keep their per-iteration logs below INFO: 2000 DEBUG lines at
115200 baud trip the task watchdog, which is a fault of the harness and not of the PR.
`templates/i2c_fake/` holds the fakes; each `*-common.yaml` or `*-test.yaml` is a classic ESP32 or ESP32-S3 config
that includes its `.hpp` (add `esphome: name:` for the `-common` ones):
- `ccsfake.hpp`, `ccs-common.yaml`: CCS811 at 0x5A (#21927). Answers setup and update reads and checks every
ENV_DATA write against the humidity and temperature the case set; "CCS Cases" runs edge values, "CCS Sweep" 2000
random ones and logs `SWEEP checked N bad M bad_reads R bad_writes W`. A read without a register, of a register
the fake does not model or of the wrong length gets a NACK and counts in `bad_reads`; a write other than the
driver's SW_RESET, APP_START, MEAS_MODE and BASELINE writes (each with its own length) gets a NACK and counts in
`bad_writes`. The CASES and SWEEP lines end in PASS only when something was checked and `bad`, `bad_reads` and
`bad_writes` stayed 0, and in FAIL otherwise.
- `eefake.hpp`, `ee-common.yaml`: HTE501 (0x40) and TEE501 (0x48) with CRC words; "Next" steps through raw
temperature words and logs the value a signed hundredths decode should give (#21930). A command other than
identification and measure, and a read longer than the reply, gets a NACK and counts as `bad`. The DONE line
200 ms later, after both reads, shows the running `bad` total, the measure replies each driver read and the
published values; it ends in PASS only while `bad` is 0, both drivers read a reply this case and both published
the expected temperature (and HTE501 the fixed humidity).
- `scdfake.hpp`, `scd-common.yaml`: SCD4x at 0x62 and 0x63 with Sensirion CRC; logs every `0xE000` ambient pressure
write, and the CASE and SHOW lines count writes with a bad CRC apart from the good ones. A command the scd4x driver
does not send, one sent with the wrong length (2 bytes bare, 5 bytes with one CRC word), or any other command with a
bad CRC, gets a NACK and counts as `bad writes`. A read after a command the fake does not answer, or one longer than the command's
reply, gets a NACK and counts as `unknown reads`. The second instance has a fixed `ambient_pressure_compensation`
to cover the setup path (#21935). Each CASE line ends in PASS only when bad CRC, bad writes and unknown reads did
not move, the `0xE000` writes match `expect_e000()` (none, or one with the expected value) and, for a source case,
CO2 was published. `RANGE_CHECKED` in `scdfake.hpp` picks the rule: false truncates as dev does, true skips values
outside 700 to 1200 hPa and rounds as #21935 did. The SHOW line ends in PASS when nothing bad was counted, neither
instance failed and 0x63 got exactly one write of its fixed value.
- `sxfake.hpp`, `sx-common.yaml`: two SX1509 register files with reset values and the `7D 12/34` reset, recording
every write. Only a byte that lands on RegReset (0x7D) drives the reset, so a burst through it keeps the bytes for
0x7E and 0x7F. A read without a register, or a transfer past 0x7F, gets a NACK and `dump_log()` warns with the
count. Compare per address: hub setup order can legitimately move between hubs (#21897). Outputs of an Apply
platform are distinct template types, so a lambda list of them needs
`std::initializer_list<output::FloatOutput *>{...}`. Each case ends with an END line, PASS only while no write was
dropped and no transfer was bad; the writes themselves are judged by the diff.
- `msfake.hpp`: eight MS8607 pressure/temperature fakes at 0x76 and up and humidity fakes at 0x40 and up, with faults
per device (reset NACKs, bad PROM CRC4, zero D1 every Nth read, humidity CRC8 errors, out of range D2, full scale
humidity). It counts every command, so skipped conversions show in `report()`, and an ADC read with no conversion
pending answers 0 like the real chip and counts as `adc_no_conv`, and a humidity read with no measure pending gets
a NACK like the real chip in no-hold mode and counts as `read_no_measure` (a reset aborts either); each injected
fault counts when it is delivered (`inj_reset_nack` with `reset_nack_left`, `inj_zero_d1`, `inj_bad_crc`), so a
run that never reached a fault path shows 0 there; a PROM read, conversion or humidity measure
before that device's first reset counts as `no_reset`; a humidity read of any shape but a bare
3 byte read, and a pressure/temperature read that is not a 2 byte read of a PROM word (even addresses 0xA0 to 0xAC) or
a 3 byte ADC read, gets a NACK and counts as `bad_reads`; a bare read answers the last PROM or ADC pointer and never
repeats a reset or conversion; a command write the fake does not know, or one longer than a
byte, gets a NACK and counts as `bad_cmds`. Point both the component and its `humidity_i2c_id` device at the bus. That
driver logs no values, so give each sensor an INFO `on_value` log (#16487).
- `htfake.hpp`, `ht16k33-char-test.yaml`: HT16K33 chips at 0x70 to 0x77 (0x74 and 0x76 NACK) keeping the 16 byte
display RAM and a command trace, rendered back as text for the Adafruit 0.56" 7-segment backpack ("12:34",
decimal points, "!" for stray bytes); a read gets a NACK and counts as malformed. The test runs 64 checks (setup order, font, colon and dots, chained chips,
printf/strftime/clock, dimming, blink, standby, NACK) and ends with `ALL DONE pass=N fail=M` and PASS or FAIL (#8520). It found a
crash (null glyph table) when one display had `add_characters` and another did not.
- `ssfake.hpp`, `seesaw-test.yaml`: Adafruit seesaw at 0x36 (ATtiny817), 0x49 (SAMD09) and 0x4A (NACK): status,
GPIO bulk with the pull latch, ADC, touch, encoder and NeoPixel with chunk offsets, and the write to read gap per
module. A read it does not model, a write without a register and a write to a module or register it does not model
(or with the wrong data length) get a NACK and count in `bad`. A 100 ms interval step machine drives it and ends with `ALL DONE` and PASS or FAIL (#13538).
- `bldcfake.hpp` (three M5Unit-BLDC units at 0x65 to 0x67 with simple motor physics, one that never spins down),
`gtfake.hpp` (GT911 at 0x5D: switches, max values, touch points and key byte) and `sdpfake.hpp` (SDP3x/SDP8xx at
0x21 to 0x26: product IDs, an unknown product, a failing read every third time, a failing ID read, stop refused
while idle) have no config yet; wire them the same way. Each fake sets up its own faults in its constructor, so
there is no init step to call. Each NACKs a read it does not model or one of the wrong
length, and a write or command it does not know, and counts them as `bad_reads` and `bad_writes` (`bad_cmds` for
the SDP) in `report()`; check those are 0. The SDP report also counts each injected ID read NACK at 0x24 as
`id_fail`, so 0 there means the driver never reached that fault.
Check the PR head again just before posting results: a head that moves during a run means a retest.
## Pico 2 W as an I2C target (#22236)
`scripts/pico_i2c_target/`: `picofake.hpp` is a raw RP2350 I2C0 interrupt handler on GP4 (SDA) and GP5 (SCL) at 0x76 that
answers one byte per read request from a 256 byte register file, so any read length is byte exact. `picofake.yaml`
plays a BME280 (`chip_id` 0x60) or BMP280 (0x58) with the datasheet calibration; every 15 s it switches between the
datasheet example readings and the 0x80000 "no measurement" values, and logs `STAT` counters every 5 s. `bad`
counts reads and writes of registers the drivers do not use (soft reset only with 0xB6, read pointer wrapping past
0xFF). The DUT is
an ESP32-C3 (`dut-common.yaml`, GPIO6/GPIO7) with two sensors on the one fake (`dut-bme280.yaml`,
`dut-bmp280.yaml`), the second with oversampling NONE. `run.sh bme280|bmp280 LABEL` flashes the DUT, starts the
fake capture and waits for a `STAT` line as the baseline, then resets and captures the DUT and prints the distinct
values per sensor. The fake capture runs on until a `STAT` line arrives after the DUT capture ends, so that line
covers the whole run. It prints PASS when every sensor gave a numeric state, that `STAT` line came, and the fake's
`abrt` (read replies the controller aborted) and `bad` counts did not move from the baseline; diff the output of dev
and the PR.
The ESP32-S3 I2C slave v2 driver cannot emulate a register device: answering from a task and straight from the ISR
both gave shifted multi-byte reads. Use the Pico.
## DS2482-800 simulator (ds248x)
`scripts/ds248x_sim/`: `dssim.yaml` with `sim.hpp` turns a Pico 2 W into a DS2482-800 at 0x18 (GP4 SDA, GP5 SCL)
with four DS18B20s: channel 0 at 21.5 °C, channel 1 at 33.0 °C, channel 2 at -5.25 and 40.0 °C. The DUT is an
ESP32-C3 (`dspd.yaml`, GPIO4/GPIO5 plus GND); the internal pull-ups are enough at 50 kHz. Faults are one character
on the Pico's USB console: `c` NACKs the read pointer write after the next channel select, `z` NACKs the 9 reads
after the next 0xBE, `b` and `k` stick busy with a failed reset or config write, `x` and `X` make it dead and alive.
`SC=<serial_capture.py> python3 drive.py TAG SIM_PORT DUT_PORT [c,cd,z,b,k,dead]` (default `c,z,b,k,dead`; `cd`
runs the `c` fault densely, 28 times about 3 s apart) resets the DUT per phase and prints
readings, wrong values, log counts and the simulator's counters (`wrong_ch` counts ROM matches on the wrong
channel). The DUT is captured with `--ms` so the log can be split at the last fault: the recovery window starts
`SETTLE` (3) seconds after it. A phase fails when any of the four sensors got no correct reading in the recovery
window, the DUT logged a CRC, held low, busy timeout or no response line in it, a temperature is wrong, a phase other
than `dead` logged `recovery failed`, `DS248x hub failed` or a component marked failed, a ds248x warning is still
set at the end of the phase, the DUT capture
failed (stderr in `TAG-<phase>.err`), a fault moved its injection counter (counted when the DUT meets the
fault, not when it is armed) by other than the number of faults sent (`arm_lost` counts arms that landed while one
of the same fault was still pending and merged into it), a NACK fault never moved `nacked`, a write delivered data while a NACK was armed
(`nack_miss`, also counted when the write is followed by a repeated start into a read; the NACK never reached the wire and stays pending), the DUT sent an address-only write (`empty_wr`), a write was cut off by a repeated start into another write and
never processed (`dropped`),
a fault is still pending (`pend=1`) at the end of the
phase, the simulator counted a config write with a wrong complement (`cfg_bad`) or an unknown, short or overlong
command (`bad_cmd`), a counter is missing from the simulator's CNT line, the simulator aborted a read reply
(`tx_abrt`, not gated in the `dead` phase, which switches the controller off), a phase other than `b` and `k` (which
reset the chip under the driver) counted `wrong_ch` or a 1-Wire command without the active pull-up bit (`ops_no_apu`),
the simulator never logged `DEAD` for the `dead`
phase, or the DUT log of the `dead` phase has no sign of the outage (`did not respond`, a ds248x warning,
`DS248x hub failed` or a component marked failed). It ends with PASS or `FAIL:` and the failed phases. The whole
phase CRC, held low, busy timeout and no response counts are printed for information: the faults cause them.
- Sensors polled at the same interval go through the channels in blocks, so a stale channel cache never shows.
Poll them at different intervals, as `dspd.yaml` does (1, 1.3, 1.7 and 2.3 s).
- The NACKs use the RP2350 `slv_data_nack_only` register, set at STOP.
- A NACKed write and an address-only write both end with no data, so the simulator cannot tell them apart.
The ds248x driver never sends one, `dspd.yaml` sets `scan: false` and the simulator only sees STOPs after its
own address, so `empty_wr` (address-only writes outside a NACK window) stays 0; a nonzero count means `nacked`
may include writes that never carried a NACKed byte.
## I2C fault injection in software (vl53l0x)
`scripts/i2c_fault/`: `faultbus.h` wraps the real `I2CBus` and returns NACK for chosen transfers to one address. An
`on_boot` priority 800 lambda swaps the sensor's bus (`id(d)->set_i2c_bus(&fb)`) before its setup, and an interval
arms the faults. `vlpf.yaml` runs a VL53L0X on an ESP32-S3 (GPIO8/GPIO9) through quiet, fault A (the next
measurement-in-progress read fails), quiet, fault B (the next measurement start fails) and quiet phases over 150 s,
with a model ID probe every 10 s to tell a driver stall from a dead chip. `run.sh LABEL` builds, flashes, captures
and runs `an.py`, which counts readings per `PHASE` line. Each `PHASE` line clears a fault that was armed and has
not fired yet and logs the fired totals so far, so `an.py` counts the fires of each phase. It fails when the phases are not quiet, faultA, quiet,
faultB, quiet (a short capture or a restart), the first quiet phase has no readings, a later quiet phase reads less
than half as often as the first, a later quiet phase reads NaN (`nan` or `-nan`) or logs the driver's "update called before prior
reading" warning when the first did not (a target out of range reads NaN in every phase), a quiet phase has a failed
model ID probe, one that did not return 0xEE or no successful probe at all,
anything crashed or rebooted, or a fault did not fire in its own phase or fired in another one.
Prefer this to glitching the wire. Holding SDA low by rerouting the pin (`esp_rom_gpio_connect_out_signal` to
`SIG_GPIO_OUT_IDX` and back to `I2CEXT0_SDA_OUT_IDX`) wedges the ESP-IDF controller, which then needs
`i2c_master_bus_reset()` after each glitch, and glitches timed onto writes left the VL53L0X answering 0x00 until a
power cycle.
.agents/skills/hardware-test/reference/recipes/gpio_hold.md
+17
View File
@@ -0,0 +1,17 @@
# ESP32 GPIO hold through the ISR pin API (#21576)
`scripts/gpio_hold/hold_test.hpp` builds `ESP32InternalGPIOPin`s by hand, calls `to_isr()` and reads each pad back
with `gpio_get_level`: 20 ISR writes, a raw `gpio_set_level` control (a held pad must not change, an unheld one must)
and ISR `pin_mode` pulls (input must drop to `NONE` between pull changes, because the ISR path only applies pulls when
`FLAG_INPUT` toggles). It needs no wiring: unconnected pins read the pulls. Each pin runs held and unheld, then the
round logs `ROUND n PASS failures=0` or `FAIL`.
- `USE_GPIO_HOLD` comes from any pin with `hold_state: true`, so the configs add a `gpio` output on a spare pin.
- `gpio-hold-esp32.yaml` (classic devkit) runs three rounds 5 s after boot and has a `rerun` button;
`gpio-hold-esp32s3.yaml` (Waveshare ESP32-S3-ETH, where most pins go to the W5500, TF card, camera, WS2812 or
USB) runs a round every 15 s.
- C3: ESP-IDF 5.5 has `SOC_RTCIO_PIN_COUNT` 0, so `rtc_gpio_is_valid_gpio()` is false on every pin and only the
digital hold path runs.
- C6 (Waveshare ESP32-C6-GEEK, native USB): LP pads GPIO0 to 7 are RTC IO with hold. GPIO1, 2, 7, 20, 23 read high
and GPIO6 low whatever the pull (LCD, TF card or resistors); clean pins are 0, 3, 4, 5, 18, 19, 21, 22. Dev
already holds LP pads through `gpio_hal_hold_en`, so the PR and dev look the same there. H2 is untested.
.agents/skills/hardware-test/reference/recipes/https_idf.md
+26
View File
@@ -0,0 +1,26 @@
# HTTPS on web_server_idf (#22185)
#22185 adds an HTTPS developer API to `web_server_idf` with no YAML option, so `scripts/https_idf/` brings a test
component: `ext/httpstest` (`httpstest.hpp`) serves `/hw` (a status line with mode, request count and free heap),
`/hw/big` (16 KB) and `/hw/switch/{http,https,https8443,bad}`. A switch runs on the main loop through `defer()`, or
3 s later with a `/later` suffix (a stalled TLS client holds the server task, so its switch is armed first), and
calls `set_ssl_credentials(cert, key, port)`: plain HTTP on 80, HTTPS on 443 or 8443, or a key that does not match
the certificate. Its schema uses `web_server_idf.consume_ssl_sockets`. The run-time switch is the follow-up API; on a
tree that only has #22185, drop the switch paths and set the credentials once before `init()`.
Copy the directory into a scratch directory with a `secrets.yaml`, then `run.sh LABEL` (env `TREE`, `PORT`, `SC`,
`PY`): it runs `make_certs.sh` (a self-signed P-256 certificate, its key and an unrelated key in
`ext/httpstest/certs.h`; test material, never commit it), builds `https-dut.yaml` (ESP32-C3, logs on USB), flashes,
takes the address from the serial log and runs:
- `t1.sh HOST`: one GET with the TLS time, 20 sequential, 6 parallel three times and the 16 KB body. The fixture has
no event source, so the 501 that #22185 sends for an event stream on HTTPS is not covered here.
- `stall.py HOST`: arms a switch to HTTP and to 8443, opens two idle TCP clients (no ClientHello) on 443 before it
runs, then switches back; every switch must be accepted and work, and the idle clients must be closed.
- `t2.sh HOST`: HTTP and back, an armed switch to 8443 with a client open that sends a handshake record header and
never the rest, 60 requests that must all get a 200 for a heap check (compare the `/hw` heap before and after),
then the bad key. The server must log the error and stay off, without falling back to plain HTTP; reset the board
afterwards.
The runner fails on any unexpected status, a missing key error for the bad key, a reset or a task watchdog. `https-soak.yaml` adds a switch between 443
and 8443 every 20 s for a long run with clients attached. Each HTTPS connection takes about 26 KB of internal RAM
(no PSRAM on the C3), so watch the `ALIVE heap=... min=...` lines.
.agents/skills/hardware-test/reference/recipes/hub_input_sim.md
+21
View File
@@ -0,0 +1,21 @@
# matrix_keypad, wiegand, rdm6300 and key_collector without hardware (#21787, #21788, #21790)
All on a D1 mini with no wiring: `scripts/hub_input_sim/hub.yaml` and `sim.hpp`.
- Keypad: one row (GPIO5) and columns GPIO4, 14 and 12 with pull-ups. `sim::press(pin)` switches the column to
`OUTPUT_OPEN_DRAIN` driven low, so the single row reads that key pressed on every scan; `sim::release` goes back
to `INPUT_PULLUP`.
- Wiegand: D0 on GPIO13, D1 on GPIO0. Call `sim::wiegand_arm()` once, then `sim::wiegand(value, bits)` sends the
pulses (80 us low, 1.5 ms apart, most significant bit first). `pinMode(OUTPUT_OPEN_DRAIN)` clears the pull-up and,
with the output latch low, makes a falling edge that adds a bit: write `GPOS` high before the mode switch and set
`GPF |= 1 << GPFPU` after. The interrupt type survives `pinMode`.
- rdm6300 reads UART0 with its loopback bit set (`USC0(0) |= 1 << UCLBE`), so the logger runs with `baud_rate: 0`
and the log goes over the API. Frames are 0x02, 12 ASCII hex characters (version, 4 id bytes, xor) and 0x03. The
uid binary sensor pulses on and off per read.
- key_collector takes both the keypad and wiegand as `source_id`.
- `run.sh LABEL` flashes over serial, reads the API log until `DONE` and writes `out-hubsim<LABEL>.ev`; diff the
`[ev` lines of dev and the PR.
- Wiegand frames with valid parity: 26 bit 0x3579bdf (11259375), 34 bit 0x3bd5b7dde (3735928559), 37 bit
0x1b4b4b4b4a (24253932965). 0x3579bdd fails parity, so only `on_raw` fires for it.
- rc522 and sx1509 need their chips; compile them only.
- Results: https://github.com/esphome/esphome/pull/21790#issuecomment-6491675405
.agents/skills/hardware-test/reference/recipes/hx711.md
+28
View File
@@ -0,0 +1,28 @@
# hx711 without a chip: fake HX711 on the same ESP32 (#8899)
`scripts/hx711`: classic ESP32, no wiring. SCK is GPIO32, DOUT GPIO33 (configured as an input with pull-up, so DOUT
reads busy until the fake runs). `hxsim.hpp` starts from `on_boot` priority -100 (after the component has set up its
pins), switches both pins to `GPIO_MODE_INPUT_OUTPUT` (it reads the clock and drives the DOUT level the component
reads back) and runs a task pinned to core 0 (the ESPHome loop runs on core 1; core 0's idle task is removed from
the task watchdog).
- Ready means DOUT low; the task waits for the clock with interrupts off in 2 ms windows. Each rising edge puts the
next bit out and the 25th sets DOUT high; extra pulses pick the next conversion (25 A/128, 26 B/32, 27 A/64), and
each conversion takes 100 ms. Clock high for more than 60 us is power down (back to A/128), clock low powers up.
- Values encode the conversion: A/128 is 128000+n, A/64 64000+n, B/32 -(32000+n), so a published value shows which
conversion it came from. `check.py CAP...` matches every `Got value` against the served values and exits non-zero
on an unmatched value, no values or a crash.
- `mode`: 0 normal, 1 DOUT stuck high, 2 DOUT left low after the read.
- The waiting and shifting code must run from IRAM. `IRAM_ATTR` on inline class members either gets inlined into
flash code or fails to link ("dangerous relocation: l32r: literal placed after use"); use static free functions
with `IRAM_ATTR __attribute__((noinline))` and check with `xtensa-esp32-elf-nm` that they sit at 0x4008xxxx. Run
from flash, the first transfer after boot lost one clock pulse (the value shifted right by one bit). Log from the
main loop (an interval drains an event ring), never inside the critical section.
- Runs: `hxbase` (65 s), `hxpr1` channel B plus set_gain and power actions (115 s), `hxpr2`
power_down_after_reading (45 s). `hx-common.yaml` starts each run's `run_all` script and logs the `DONE` line.
`build.sh NAME TREE LABEL` writes `NAME<LABEL>.yaml` with its own name (so dev and the PR builds of the same config
do not share a build directory) and builds it; then `flashcap.sh DIR NAME<LABEL> TREE SECONDS` (`PORT`, `SC` in
the environment), which fails without a `DONE` line and runs `check.py`.
- The configs have no Wi-Fi on purpose: the fake keeps core 0 busy with interrupts off in 2 ms windows, which would
starve the Wi-Fi task. Keep the harness without Wi-Fi, API or OTA.
- Result on #8899: no missed pulses over 141 transfers, and every published value matched.
.agents/skills/hardware-test/reference/recipes/i2c_slave.md
+16
View File
@@ -0,0 +1,16 @@
# Fake I2C slave (#21586)
`scripts/i2c_slave`: a D1 mini running an Arduino `Wire` slave at 0x40 (`i2cslave.yaml` with `i2cslave.hpp`): a fake
HDC1080 plus a 256 byte register file, and reads of 0x7E and 0x7F stretch the clock for 0.5 and 5 ms. It needs
`libraries: [Wire]` and 160 MHz. With jumper wires only and the internal pull ups it works to about 50 kHz; it cannot
keep up with a true 100 kHz hardware master.
The master (`i2cbk.yaml`, a BK7238 on P26/P24, needs the software I2C bus from that PR) writes a counter, reads it
back with a repeated start, probes an absent address and reads both stretch registers every 2 s, logging `RW OK`
(the read back matches, the absent address NACKs and both stretched reads succeed) or `RW BAD` with running totals.
Control: the same blocks on a classic ESP32 devkit (SDA GPIO21, SCL GPIO22) with hardware I2C at 25 and 50 kHz got
every repeated start read right, so failures on a bit banged master at a similar real clock point at the master.
On the NiceMCU WB3S V1 board (BK7238), P26 and P24 are on the right-hand header.
Fake devices that need no real chip (in-firmware buses, the Pico 2 W target, the DS2482-800 simulator, NACK
injection) are in [fake_i2c.md](fake_i2c.md).
.agents/skills/hardware-test/reference/recipes/i2s_audio.md
+14
View File
@@ -0,0 +1,14 @@
# i2s_audio
## I2S microphone loopback on one S3 (#22130)
With no I2S microphone at hand, `scripts/i2s_loopback/` makes one. `dcgen.hpp` runs an ESP-IDF std TX channel on
I2S1 as master (GPIO4 BCLK, 5 WS, 6 DOUT, 16-bit stereo) in its own task, switching patterns (DC step, opposite DC
per channel, DC plus a 1 kHz tone, full and half scale 50 Hz squares) through `dcgen::set_mode()`. Jumper 4 to 15,
5 to 16 and 6 to 17 to an `i2s_audio` microphone on I2S0 with `i2s_mode: secondary`. `dcgen::on_data` (registered
with `add_data_callback`) keeps per-segment and last 500 ms stats plus a 1 ms trace of channel 0, and `report()`
logs `SEG` and `SETTLE` lines from an interval. `run.sh LABEL [SAMPLE_RATE] [CHANNEL]` flashes and captures 60 s,
and `sum.py` tabulates. The segment min and max include the tail of the previous pattern (capture latency), so judge
with the tail values. The runner fails on a missing segment, a full-scale square under rms 8000 (no signal through the
jumpers), on either channel for a stereo run, or a crash after the first segment.
Results: https://github.com/esphome/esphome/pull/22130#issuecomment-6615554179
.agents/skills/hardware-test/reference/recipes/ld2420.md
+21
View File
@@ -0,0 +1,21 @@
# ld2420 without a module (#21914)
`scripts/ld2420_sim/` runs the hub on a D1 mini UART0 with the loopback bit set and no radar. A `uart: debug` TX hook
(delimiter `04 03 02 01`, the command footer) hands each command frame the hub sends to `ldsim::on_tx()`, which writes
a success ack right behind it: the hub reads its own echo and then the ack. The acks carry the version (the `fw`
substitution), the min and max gate and timeout registers and the gate parameters, so `setup()` completes (`Sim stats`
logs `cmds 21 acks 21`). Template buttons then inject energy frames (`Energy steps`) or simple mode `ON`, `OFF` and
`Range N` lines (`Simple steps`). Firmware v1.5.3 or older keeps the hub in Simple Mode.
- `run.sh LABEL energy|simple HOST` builds, flashes and records two `lddrive.py` runs over the API; `compare.py` takes
the same run of two builds and prints PASS when the state sequences after the steps button match, every setup
command was answered, a Distance and a Presence state arrived and no ERROR line was logged.
- The loopback bit is set at `on_boot` priority 900: after the UART is set up and before the hub's blocking `setup()`.
- `fire_trigger_()` hands the debug lambda the debugger's own buffer, which writing the ack changes; `on_tx()` copies
it first, and ignores its own acks (command high byte 0x01) when the nested call sees them.
- The hub also reads its own echoed command frames. A read register command carries `00 00` where an ack has its error
word, so the echo counts as that command's ack and every real ack lands one command late. The Firmware text sensor
published during `setup()` therefore shows `v0.0.0` in this harness; the config dump and the Simple Mode check see
the simulated version. A real module does not echo, so this harness cannot check that text sensor value.
- Energy mode and simple mode publish at most once a second; a burst of 5 frames 100 ms apart publishes only the first.
- Results: https://github.com/esphome/esphome/pull/21914#issuecomment-6517294344
.agents/skills/hardware-test/reference/recipes/ld2450.md
+26
View File
@@ -40,3 +40,29 @@ least 24 selects per build and read the raw bytes with `uart: debug: direction:
id) before blaming the parser; the API log stream drops lines under that dump volume, so some misses stay
unclassified.
Results: https://github.com/esphome/esphome/pull/21357#issuecomment-6333244886
## Frame stream harness: presence hold and link loss (#21733, #21734)
`scripts/ld2450/stream-harness.yaml` is a loopback harness that feeds the hub one periodic frame every 100 ms from a
mode global set by API buttons: no target, target 1 approaching, silent, or 12 garbage bytes per tick (what a radar
at another baud rate looks like). `has_target` has `filters: []` so the hub's own hold is what gets timed, and every
change logs `presence raw ON|OFF at <millis>`. Add `stream-connected.yaml` as a second package on builds whose ld2450
has the link watchdog (`connected` binary sensor).
- `holddrive.py HOST OUT`: for `presence_timeout` 5 and 0, three seconds of target frames, then empty frames; prints
the ms from the press to the off line, then sets 0 and 20 and reads the number back after a restart. On dev 0
still held 5 s and snapped back to 5; with #21733 it clears on the next empty frame (under 200 ms) and stays 0.
- `linkdrive.py HOST OUT`: steps through target frames, 10 s of silence, empty frames, 10 s of garbage, target
frames, then the hub's radar restart followed by 3.5 s and by 15 s of silence; prints every state change and link
log line with its time. Dev freezes every entity through silence and garbage. Run against a real radar too: a
radar restart and a Bluetooth toggle must not report a loss (the Apollo R PRO-1 ETH did not).
- A freshly booted ESP8266 delays API commands sent in its first seconds and then runs them back to back; the
drivers wait 8 s after connecting before timed presses.
## BT MAC sensors (#21731)
`scripts/ld2450/macdrive.py HOST OUT` reads every LD24xx BT MAC, Bluetooth and firmware entity, turns each Bluetooth
switch off, then on, and prints the values after each step. The MAC sensors are often `disabled_by_default` in
vendor configs but still publish over the API. On the Apollo R PRO-1 ETH both radars (LD2450 fw 2.04, LD2412 fw
1.26) have the multicast bit set in the first MAC byte, which dev showed as `unknown`. A radar MAC identifies a
device: quote only its first byte in PR text.
.agents/skills/hardware-test/reference/recipes/led_driver_sniff.md
+29
View File
@@ -0,0 +1,29 @@
# Bit-banged LED drivers without the chips (#21841 to #21847)
The GPIO LED drivers (bp5758d, bp1658cj, sm2235, sm2335, tlc5971, tlc5947, my9231, sm16716) never read the chip
back, so a classic ESP32 devkit can capture its own pads with no wiring. `scripts/led_driver_sniff`.
- `sniff.hpp`: SPI2 and SPI3 run as DMA slaves fed from the driver's clock and data pads through the GPIO matrix
(`esp_rom_gpio_connect_in_signal`, pad input enabled with `gpio_input_enable`). Mode 1 samples on the rising edge
of its clock input (measured, not what the mode table suggests): SPI2 takes the clock straight (rising-edge bits,
`R` lines) and SPI3 inverted (falling-edge bits, `F` lines; my9231 clocks a bit on both edges). CS is GPIO2,
driven by the test. PCNT counts clock and data edges and latch rises per window.
- ESP32 slave DMA drops a partial last word, so `close()` pads the clock with whole pulses to a 32-bit boundary plus
32, and the bit count comes from PCNT. `selftest()` sends a known 57-bit pattern with the clock idling low and
high; `selftest.py` checks it, and `run.sh` runs it on every capture.
- bp5758d, bp1658cj and sm10bit_base (sm2235, sm2335) release the data line for the ack with `pin_mode(INPUT)`, and
`pin_mode(OUTPUT)` disables the pad input. The `sniff` local component (`ext/`) links with
`-Wl,--wrap=gpio_set_direction` and the header re-enables input on the sniffed pins. The ack bit reads the
floating line, the same on every build.
- `gen.py` writes `led.yaml`: all eight drivers on separate pins (bp5758d 25/26, bp1658cj 23/4, sm2235 18/19, sm2335
21/22, tlc5971 27/32, tlc5947 33/13 latch 14, my9231 16/17, sm16716 5/12, selftest 15/0) and a script per driver:
one window per step (open, set levels, 200 ms of main loop, close), a repeated step that must send nothing, two
direct `loop()` calls timed with `esp_timer`, and an idle window.
- `run.sh LABEL` builds, flashes, captures until `DONE` and checks the selftest. `compare.py BASE PR DRIVER` diffs
every window of one driver between two runs and decodes it (9-bit groups for the BP and SM frames, 12-bit words
for tlc5947, 16-bit for tlc5971, the two-edge interleave for my9231, 50 zero bits plus 25-bit groups for
sm16716). Loop timing varies about 3 % between builds even for drivers a PR does not touch.
- my9231 toggles DCKI with `!digital_read()`. ESP32 output pins have the pad input disabled, so without the
sniffer's input enable the read is always 0 and the clock never toggles (on dev too).
- Out-of-range channels: run `esphome config` with channel = last and last + 1 on dev and the PR.
- Results: https://github.com/esphome/esphome/pull/21844#issuecomment-6491228132
.agents/skills/hardware-test/reference/recipes/led_strip.md
+53
View File
@@ -8,3 +8,56 @@
- On the ESP32-S3 give each RMT strip `rmt_symbols: 48`, or the first channel takes all 192 symbols.
- A board with a few WS2812 on a pin already defined as a light can be extended with `id: !extend <light id>` to
add effects; restore its own config afterwards.
- Loop cost of a strip (#19337): give each strip an `addressable_lambda` effect with `update_interval: 0ms` that
changes every pixel, and add `runtime_stats: log_interval: 30s`; compare the main loop and light times per pass,
leaving out the first period after boot. The strips need no LEDs attached. A classic ESP32 has 512 RMT symbols in
all, so three strips need `rmt_symbols: 128` each.
## RMT channel and memory budget (#22172)
`scripts/rmt_budget/`: each line of `cases.txt` is a mix of strips, transmitters and receivers with their
`rmt_symbols` (`s:96`, `t:def`, `r:48`, ...) on an ESP32-S3 or ESP32-C6, and `gen_case.py CASE` turns it into a
config whose strips have an `output_id` and which logs `STATUS so0=<is_failed> tx1=...` every 3 s. `run.sh CASE...`
builds each case under one name per board (so builds stay incremental), flashes, captures 15 s and prints the STATUS
line and the RMT driver errors; it exits 1 when a case printed no STATUS. `verdict.sh CASE...` runs only
`--only-generate` and prints the config errors, the RMT memory warnings and the components registered, to compare
with what the board then does. No LEDs are needed: allocation failures show at boot.
- On the S3 USB console the ESP-IDF `no free tx channels` lines are printed before the port reopens; the C6 on
UART0 shows them.
- S3 TX channels can use RX memory (384 symbols at most) but only start on blocks 0 to 3, so two 192 symbol strips
do not fit.
- 17 of 17 predictions of the PR matched the driver. Results:
https://github.com/esphome/esphome/pull/22172#issuecomment-6615083139
## Capture the wire, not the buffer (#21577)
`templates/led_wire/wire.hpp` reads what the strips send, with no wiring:
- RMT RX channels on the `esp32_rmt_led_strip` pads at 10 MHz, decoded with a high-time threshold per chipset
(ws2812 0.4/0.8 µs: threshold 7 ticks; sk6812 0.3/0.6 µs: threshold 4);
- an SPI2 DMA slave fed from the `spi_led_strip` pads, with `spi: interface: spi3` for the strip.
`led-wire-dut.yaml` (classic ESP32) drives a GRB ws2812 strip, a GRBW sk6812 strip, an SPI strip, an RGB light and a
partition through steps S0 to S8 (on, `addressable_set`, lambda writes, partition, effect, power limit, off), logging
the decoded `RMT`, `SPI` and buffer `GET` lines and `DONE` per step, then runs `stress_step()` over 300 shows and
logs bad frames per strip. Diff the step lines of dev and the PR.
- A comparison of the buffers alone missed a PR bug in which the start frame was not sent.
- Give the captured strip `rmt_symbols` that hold a whole frame (192) and capture one RX channel at a time: with 64
symbols the TX refill interrupt stretches bits on dev and the PR alike while the capture runs. The substitutions
at the top of the config pick the strip.
## rp2040_pio_led_strip: a self-sampling PIO probe (Pico 2 W)
`scripts/pio_probe/pioscope.hpp` samples any GPIO from PIO2 at 25 MHz while another peripheral drives it (PIO reads
the pad without taking the pin) and decodes WS2812-style pulses into bit timings and bytes; no wires or LEDs.
`pa.yaml` probes five strips on PIO0 and PIO1 (WS2812 and two custom timings), `pc.yaml` one strip after claiming
DMA channels 0 to 11. `run.sh pa|pc LABEL` builds, flashes, captures 40 s and prints the `RESULT` lines; a correct
frame of two LEDs set to `Color(0xA5, 0x3C, 0x0F)` reads `3ca50f3ca50f`.
- Turn the light on at full brightness before probing, or color correction writes zeros.
- The probe FIFO overruns once in a while: count only full captures. `run.sh` fails unless every strip gave at least
one correct frame.
- An RP2350 `panic()` escalates to a HardFault and the rp2 crash handler reboots within about a second, so a panic
during component setup boot-loops before USB CDC enumerates and the board looks dead (no port, no BOOTSEL drive).
Hold BOOTSEL while plugging it in and flash the UF2 drive. To see such a fault, trigger it after boot.
.agents/skills/hardware-test/reference/recipes/libretiny.md
+104
View File
@@ -56,3 +56,107 @@ OTA-only board: copy the device's own config, add the probe include and the step
next to that config. A LibreTiny OTA is a 1.5 MB UF2 and takes minutes on a slow link, so do not wrap the
upload in a short timeout. Read the replayed report with `esphome logs ... --device <name>.local` (an API
client gets it on subscribe) or on the board's serial log port if it has one.
## RTL8720C crash report on the next boot (#21648)
`templates/rtl8720c-crash-buttons-dut.yaml` has one API button per case: `trap` (`__builtin_trap()`, usage fault),
`bus fault` (store to 0x70000000, imprecise, CFSR 0x400), `wild call` (call to 0xFFFFFFF1, MemManage fault with PC
0xFFFFFFF0 and LR in the caller), `isr trap` (a trap from a spare interrupt pended by software, hard fault), `hang`
(interrupts off, the watchdog resets it and nothing must be reported) and `restart`. Every boot logs
`boot reason N, crash record yes|no|n/a`; `n/a` means the handler is not built, as on a dev control build.
Flow per build: flash with `flash_rtl87xx_kit.py`, start one `serial_capture.py PORT 600 OUT --released --ms`, then
`scripts/libretiny_crash/rtl_drive.py HOST OUTDIR TREE YAML trap restart "bus fault" "wild call" "isr trap" hang restart`.
The `restart` after the first crash checks the report shows only once. Time each reset from the serial capture
(the ROM fault dump to the next `ROM Version` line), not from the API port: the board is back before an API client
notices it went away. Compare the reported PC with the `PC =` line of the ROM dump, and check the decoded lines in the
`caseN-*.txt` files. Pass the UF2 by name (`firmware.uf2`): the build directory holds a second identically sized copy.
Regression rerun of the same flow (#21728): `scripts/libretiny_crash/rtl_rom_vs_report.py CAPTURE` lists, for each ROM
fault dump in a `--ms` capture, the ROM's CFSR and PC, the ms to the next `ROM Version` banner and the Reason, CFSR, PC
and SP the next boot reported, so two builds compare line by line. The ROM lines start with a bare CR; split the
capture on newlines only. The imprecise bus fault's PC moves between builds (it is wherever the core was when the
fault was raised); compare it with that run's ROM dump, not with another build. SP stays the same per fault (8 word
frame, no FPU). On the BK7238 time the reboot from the button press to the next `BK7238_1.0.14` banner (0.6 to 0.7 s).
## BK7238 BLE and flash sector safety (#21735)
The Beken BLE bond store reads its partition at boot and erases that sector when the CRC does not match; before
LibreTiny 1.14 the partition was unmapped and pointed at sector 0, erasing the bootloader (#18646). To prove a change
like this safe on a board that cannot be recovered without a dump:
1. Take a full backup first: `scripts/bk72xx_flash/readback.sh full-before` (ltchiptool family `beken-7238`, about
190 s for 2 MB). Keep it until the board is back on a known build.
2. Serial flash a build without the feature, then deliver the feature build by OTA (the path users take). Use
`bk72xx: framework: sdk_silent: none` with `logger: hardware_uart: UART1`, so the SDK's own lines (bootloader
banner, `CRC fail, remove bonded info`) show up in the capture.
3. Soak with Wi-Fi up, OTA again from the new build, pulse CEN a few times (`serial_capture.py --reset`), and check
each boot comes back through the bootloader.
4. Read the whole chip again and run `scripts/bk72xx_flash/partdiff.py full-before.bin full-after.bin
<libretiny>/boards/_base/beken-72xx.json`: bootloader, calibration and userdata must be unchanged; app, download
and one KVS sector change normally.
Check what already sits in the target partition before the first boot: on an XH-WB3S that shipped with Tuya firmware,
0x1E1000 (the `ble_bonding` partition of the generic Beken layout) held the Tuya `diff2ya` record (magic `ba dc cd
ab`), which the bond store erased on its first boot. Nothing depended on it there, but say so in the results.
## BK7238 OTA and the board layout (issue #18222)
A BK7238 has one of two bootloaders, and the board in the YAML must match it: Beken OEM (`BK7238_1.0.14` in the
boot banner, `generic-bk7238`, OTA as RBL to `download` at 0x132000) or Tuya T1 2.0.0 (`generic-bk7238-tuya`,
`t1-*`, `download` at 0x12C000 plus a `diff2ya` record at 0x1E1000). `ltchiptool uf2 info` on `firmware.uf2` shows
the layout an image targets (`FAL_PTABLE`, `OTA_PART_INFO`). Measured on the OEM bootloader (2026-10-27):
| Running | Uploaded | Result |
|---|---|---|
| Tuya layout | Tuya layout | upload succeeds, bootloader prints `App verify failed! Need to recovery factory firmware.`, old build stays |
| Tuya layout | OEM layout | applied |
| OEM layout | Tuya layout | `End error: 9` (`UPDATE_ERROR_ACTIVATE`: no `RBL` at the running download offset), old build stays |
| OEM layout | OEM layout | applied |
Run it with a full backup first (`scripts/bk72xx_flash/readback.sh`), `sdk_silent: none` so the bootloader's lines
show, and each result checked against `build_info.json` over the API. A Tuya-layout build on an OEM-layout module
reads the RF calibration from 0x1E3000: copy the 0x1E0000 sector there for the test and erase it afterwards. The
Tuya OTA writes up to about 0x1EF000 and its own settings at 0x1E4000, so write those sectors back from the backup
and check with `partdiff.py`.
## RTL8710B Wi-Fi join diagnosis (issue #21742)
For a board that joins rarely: build `dev` with `sdk_silent: none`, log `wifi_get_last_error()` and
`rtw_join_status` after each failed `WiFi.begin()`, and dump the efuse map once (see the AmebaZ section in
`boards.md`). The driver log tells the stages apart: `start auth to` with nothing after it is the AP not answering,
`auth success, start assoc` then `association success` then error 3 is a failed 4-way handshake, and
`sta recv deauth reason code(6)` is the AP dropping the session mid-handshake. Tally per BSSID: if the share of
auth frames answered falls with distance while receive stays strong, the board's transmit path is weak.
A/B a value one boot at a time so time of day and AP state hit both sides equally. Keep the trial counter in a
`restore_value` global, set the value in an `on_boot` lambda at priority 600 (before Wi-Fi starts), and reboot
after a fixed window:
```yaml
esphome:
on_boot:
priority: 600
then:
- lambda: |-
// value under test, read by the code being measured
wifi::diag_value = (id(trial_idx) % 2) ? 0x3A : 0;
ESP_LOGW("trial", "TRIAL %d start value=0x%02X", id(trial_idx), wifi::diag_value);
- delay: 75s
- lambda: |-
bool ok = wifi::global_wifi_component->is_connected();
ESP_LOGW("trial", "TRIAL %d value=0x%02X result=%s", id(trial_idx), wifi::diag_value,
ok ? "JOINED" : "FAILED");
id(trial_idx)++;
App.safe_reboot();
```
Turn off `api:` and `wifi:` `reboot_timeout`, and leave out `ap:` unless the AP is the variable under test.
Do not cycle trials with `wifi.disable` and `wifi.enable`: doing that while connected reset the RTL8710B on the next
scan. Results from 2026-10-27, on one BW12 with blank efuse calibration: crystal trim `0x20`, `0x30` and `0x38`
all joined 20 of 20 trials, and boosted TX power indexes changed nothing against an AP that answered 0 of 43
auth frames.
Known LibreTiny behaviour seen here: after a join with a BSSID and channel, LibreTiny's partial-scan reset leaves
the next SSID-only join with nothing to scan (`RTW_NONE_NETWORK` in about 18 ms). That is a firmware bug, not
the board; passing channel 0 avoids it.
.agents/skills/hardware-test/reference/recipes/light_sleep_gpio_wake.md
+36
View File
@@ -0,0 +1,36 @@
# GPIO wakeup from auto light sleep (#21074)
`scripts/light_sleep_wake` needs no wiring. LEDC on `LEDC_USE_RC_FAST_CLK` with
`sleep_mode = LEDC_SLEEP_MODE_KEEP_ALIVE` keeps toggling GPIO10 at 2 Hz through light sleep, and an
`ESP32InternalGPIOPin` interrupt (`ANY_EDGE`) on the same pad timestamps every edge in an IRAM handler.
`wakeprobe::report()` logs every 30 s: edges seen and expected, the shortest and longest gap, how many edges came
more than 20 ms off the half period, and the SLEEP share from `esp_pm_dump_locks()` (needs `profiling: true`).
- Native ESP-IDF builds need `include_builtin_idf_components: [esp_driver_ledc]`.
- After `ledc_channel_config` call `gpio_input_enable(pin)`, never `gpio_set_direction(INPUT_OUTPUT)`: that routes the
pad back to a plain GPIO output, the wave stops and the pad reads a constant 1.
- The C3 shares one LEDC clock across timers, so a board whose own config drives LEDs through `ledc` needs a test
config without them. Logging over the API works with `logger: baud_rate: 0`.
- Read the reports over the API with `esphome logs ... --device <ip>` under `timeout`. Run PR, dev, then the PR
again. On a C3 bulb dev caught every edge but handled 8 of 845 more than 20 ms late
(up to 45 ms), the PR none; both slept 57 to 58% of the time.
## Peripheral power-down needs an external signal (ESP32-P4)
LEDC in `LEDC_SLEEP_MODE_KEEP_ALIVE` keeps the TOP power domain on, so the self-generated wave above never tests
`power_down_peripherals`. With that option the PR's ext1 path also hands an LP pin to the LP IO block, and an LEDC
wave on the same pad no longer reaches the input (the pad reads 0).
- `wake-stim.yaml` puts a 2 Hz square wave on GPIO25 of a classic ESP32 (LEDC on REF_TICK). Wire it to GPIO4 of the
board under test; boards on the same USB host share ground.
- `wake_detail.hpp` with `wake-detail-esp32p4.yaml` (substitution `power_down`): GPIO4 is the any-edge interrupt pin
and GPIO22, jumpered to it, is read as the true level. The first 40 s hold a `NO_LIGHT_SLEEP` lock, then sleep is
allowed. Each report counts interrupt calls, real edges (the GPIO22 level changed) and calls with no change, per
phase, and two windows (from 9.5 s and from 69.5 s) log every call with its gap and both levels. A light-sleep
exit callback counts wakes when `CONFIG_PM_LIGHT_SLEEP_CALLBACKS` is set.
- Waveshare ESP32-P4-WIFI6 (pre-rev3 silicon, CH343 console): `engineering_sample: true`, `flash_size: 32MB` and
`logger: hardware_uart: UART0`, or the app logs nothing on that port. No Wi-Fi needed. GPIO4 is the left header,
12th pin from the USB end; GPIO22 the right header, 9th.
- Result on #21074 at 2ef417bd81 with peripherals powered down: the PR caught all 644 real edges (dev 66) but added
4642 calls while the line was high, one per sleep cycle (about 16 ms), with the level read correctly. Peripherals
on: both builds caught every edge. https://github.com/esphome/esphome/pull/21074#issuecomment-6503939850
.agents/skills/hardware-test/reference/recipes/manual_ip_and_web_handlers.md
+31
View File
@@ -0,0 +1,31 @@
# Manual IP and web handler flows (#21708, #21709, #21711, #21712)
## Station manual IP (`scripts/manual_ip/run-sta.sh`)
Set `static_ip` to the board's own DHCP lease so nothing collides, and DNS2 to a server DHCP does not hand out
(9.9.9.9), so the dump and `dns_getserver()` prove the manual values are in use. A missing SSID with its own
`manual_ip` comes first, so the real network is a later table row and inherits the top level `manual_ip`. The probe
logs both DNS servers and resolves a name every 20 s; `ipaddr_ntoa` uses one static buffer, so it uses
`ipaddr_ntoa_r` to log two addresses in one line. PASS needs the address, both DNS servers, a lookup and a ping.
## AP manual IP (`scripts/manual_ip/run-ap.sh`)
The DUT has only a missing SSID, `ap_timeout: 10s` and `captive_portal:`, so its AP comes up on 10.42.7.1; the other
board joins as a client and fetches `http://10.42.7.1/` every 10 s. A D1 mini AP drops some client requests on dev
too, so compare failure counts with a dev run and do not expect zero.
## Ethernet manual IP
Same idea on an Ethernet board: its lease as `manual_ip` plus an outside DNS2 and the DNS probe from
`scripts/manual_ip/dnsprobe.hpp`; restart it over the API and check again.
## Web handlers (`scripts/web_handlers/run.sh`)
`webbase.yaml` adds a GET /probe handler from `on_boot` at priority -100 (the shape of an external component adding
a handler late) and takes a variant: `ws` (web_server), `cp` (captive_portal only, started on the station network by
a button calling `global_captive_portal->start()`) or `prom` (captive_portal and prometheus). The runner fetches
/probe and /, then uploads the same image through web OTA (`curl -F update=@<bin> http://ip/update`; ESP-IDF
`build/<name>.bin`, not `firmware.ota.bin`; ESP8266 `.pioenvs/<name>/firmware.bin`) and checks over the API that the
board is back on that build. On dev too, prometheus GET / gets no answer on ESP32 and 404 on ESP8266.
A background `(cd dir && cmd) &` does not change the parent shell's directory: give capture scripts absolute paths.
.agents/skills/hardware-test/reference/recipes/mdns.md
+18
View File
@@ -0,0 +1,18 @@
# mDNS responder (#22267)
`scripts/mdns/mdns-common.yaml` (a package) adds a `_hwtest._tcp` service with a short and a 62 character TXT
value and logs free, minimum and largest free heap every 10 s; `mdns-wifi.yaml` adds Wi-Fi from `secrets.yaml` and
switches it off and on every 120 s so the responder restarts. The host's multicast often does not reach the boards
(a host with several network interfaces, or a mesh Wi-Fi network), so the scripts send legacy unicast queries (source port not 5353)
straight to the device's port 5353 with python-zeroconf packets:
- `mq.py IP HOSTNAME dump` asks for the `_esphomelib` and `_hwtest` PTR records, the A record and the SRV and TXT
records of both services, prints the answers and exits 1 when one is missing. Diff the dump between builds.
- `mq.py IP HOSTNAME hammer N [TIMEOUT]` sends N questions back to back (0.5 s timeout each) and counts misses per
question. It exits 1 when nothing was answered, or when more than `MAX_MISS_PCT` percent (env) were missed.
- `mq.py IP HOSTNAME lat N` sends A queries 300 ms apart and prints the median, p90, p99 and maximum latency and how
many answers came after 1.5 s or never.
Judge responder timing on an Ethernet board: on a crowded Wi-Fi network back-to-back query loss swung between 0 and
14% between builds for no code reason. Run the hammer across a Wi-Fi off and on cycle too, and compare the heap
lines before and after many cycles.
.agents/skills/hardware-test/reference/recipes/microphone_http_stream.md
+26
View File
@@ -0,0 +1,26 @@
# microphone_http_stream (#21593)
`microphone_http_stream` serves raw microphone PCM at `/audio/microphones/<stream_id>` (and a listing at
`/audio/microphones`) on the web server. `templates/microphone_http_stream/`:
- `mh-base.yaml`: Waveshare ESP32-S3-ETH on PoE (logs over the API on Ethernet, the native USB port is the USB host
port), encrypted API, `web_server` on 80 with a dummy sensor and switch, mic start and stop buttons and a line
every 5 s with the mic state and internal and PSRAM heap. Any ESP32-S3 with PSRAM works for `mh-fake.yaml`.
- `mh-fake.yaml`: the stream fed by `ext/fakemic`, a test microphone that publishes 32 ms chunks of a 16-bit counter
(one count per sample) from its own task, so a reader can check every sample. Its "Mic stall" button stops the
chunks for 6 s.
- `mh-usb.yaml`: the stream fed by a USB microphone on `usb_audio` (48 kHz, 16-bit stereo, channel 0 streamed).
Copy the directory next to a `secrets.yaml` with `api_key`, flash, then run
`mhclient.py HOST STREAM_ID [--clients N] [--seconds S] [--pattern] [--stall K] [--stagger S] [--expect-reject R]`.
Each reader prints its HTTP status, format headers, sample count and rate, the longest gap between reads and, with
`--pattern`, every break in the counter. `--stall K` makes reader K stop reading after 2 s while keeping its socket
open, then checks that the device closed it. `--expect-reject R` marks the last R readers as past `max_clients`;
they must get a non-200 status or a close or reset before any samples, and a timeout or a served reader fails.
The script exits 1 when the listing is not a 200 naming the stream, the stalled reader was not dropped, a reader past
the limit was not refused, or any other reader got no 200, no samples, an early EOF, a read error or a broken counter.
Cases worth running on each head: one reader with `--pattern` (rate must match the sample rate, 0 breaks), the
`max_clients` limit plus one with `--expect-reject 1` (note what the extra one gets; the others must be unaffected), a stalled reader among
three (the device should drop the stalled one only), the "Mic stall" button during a read (a gap of about 6 s, then
the counter continues), mic start and stop while readers are attached, and the heap line after many connect and
disconnect cycles. On the USB microphone, check the rate and `rms` instead of the pattern with `--rate 16000 --min-rms 1`, and add `--max-gap-ms` to fail on long gaps; these set the exit code.
.agents/skills/hardware-test/reference/recipes/mqtt.md
+60
View File
@@ -79,3 +79,63 @@ Retest at c9cf3c2813 (shutdown message sent at QoS 1, teardown waits for the bro
boards and 3/3 deep sleeps, against 1/10, 3/10 and 0/3 on base. An earlier 100 ms hold gave 3/10, 6/10 and 2/3, so
judge a delivery fix by counts over 10 or more restarts, never one or two presses.
Results: https://github.com/esphome/esphome/pull/21566#issuecomment-6382076613
## MQTT discovery against a throwaway Home Assistant (#21956)
Run a Home Assistant dev install with its own config directory (`hass -c <scratch>/ha`) holding `http:
server_port: 8129`, `api:`, `config:`, `onboarding:` and MQTT debug logging, plus a local mosquitto on 1883. In
`scripts/mqtt/ha_discovery/`, `onboard.py DIR` creates a generated test user (the credentials stay in DIR) and a
token, `flow.py TOKENFILE` adds the MQTT entry (the `protocol` and `other_settings: {set_client_cert: false,
set_ca_cert: "off", transport: tcp}` fields are required), and `hadrive.py TOKENFILE NAME` reads the device's time,
date and datetime entities, calls `set_value` on each and reads again; it exits 1 on a missing entity, a failed
call or a state that does not read back the value that was set. The three share the REST calls in `ha_rest.py`. `dt-common.yaml` is the device side (classic ESP32, three
template datetime entities, `${broker}`).
- The HA dev branch keeps a YAML port change as a pending HTTP config and reverts it after 5 minutes. Before
starting HA again, set `data.stable.server_port` to 8129 and `data.pending` to null in `.storage/http`.
- ESPHome MQTT unique ids are name based: clear the previous build's retained discovery (`mosquitto_pub -r -n` on
each config topic) and expect the entity ids of the first build.
## mqtt.disable and broker drops on ESP-IDF (#22230)
`scripts/mqtt/disable/disable-common.yaml` disables MQTT for 30 s every 60 s (every third cycle starts with fast
toggles, a disable while connecting), publishes a tick every 2 s and logs `EV CONNECT`, `EV DISCONNECT` and
`EV MSG`. `run.sh LABEL outage|drop SECONDS` (env `TREE`, `PORT`, `SC`, `PY`, `BROKER`, `BROKER_PORT`) starts a
private mosquitto so it can stop and start it, flashes and captures:
- `outage` publishes to `md<LABEL>/in` every second and stops the broker inside a disabled window; `analyze.py`
prints per window the device connects, inbound messages, broker connects, ticks that reached the broker and the
time from enable to connect, and fails the run on a device connect or an inbound message inside a window.
- `drop` stops the broker 6 s after every enable for 15 s. This is the case that found a watchdog reset: calling
`esp_mqtt_client_stop()` while the esp-mqtt task sleeps in WAIT_RECONNECT blocks the caller for up to
reconnect_timeout/2 (5 s), 6 of 6 task watchdog resets on an S3 and a C6.
Both modes also fail when the device never connects or the broker was never stopped, and `outage` when no inbound
message arrived.
Use the host's current address for `BROKER`: a stale one gives `esp-tls select() timeout`. Before #22230 the client
reconnects on its own during disable (14 of 16 windows). Results:
https://github.com/esphome/esphome/pull/22230#issuecomment-6614854671
## Retained message burst at connect (#22200)
`scripts/mqtt/retained_burst/`: `burst-topics.yaml` (a package) subscribes 25 `on_message` topics plus 15 switch
command topics, `burst-common.yaml` logs the counts 15 s after the connect, and `seed.sh BROKER_PORT` leaves all 40 retained on a local mosquitto (`seed.sh BROKER_PORT clear` removes them).
`run.sh LABEL BOOTS` (env `TREE`, `PORT`, `SC`, `PY`, `BROKER`, `BROKER_PORT`, default board an ESP32-C3) resets the
board BOOTS times and prints `RESULT got=x/25 switches_on=y/15` and any `Dropped` lines per boot; it passes only with
40 of 40 on every boot. Before #22200 the C3 dropped exactly 49 events (80 events minus 31 slots): the main loop
drains nothing during the burst.
## Forced reconnect mid-burst (#22248)
`scripts/mqtt/reconnect/`: `kick-common.yaml` includes the same `burst-topics.yaml` and counts per connection with
a `mode: restart` script on `on_connect`, logging `RESULT` 6 s after each connect. It and `run.sh` use files from
`../retained_burst/`, so copy the whole `mqtt/` directory to the scratch directory. `kick.py BROKER_LOG BROKER_PORT
PREFIX CYCLES` tails the broker log and takes over the device's client id 0 to 400 ms after every other connect
(mosquitto drops it with "session taken over"), then leaves the next connection alone for 8 s and ends it. It
starts by kicking the connection that is already up and skips its own connections (from 127.0.0.1 with the same id).
`run.sh LABEL CYCLES` (env as above plus `BROKER_LOG`) seeds, flashes, waits for the first connect and runs the
kicker. The device counts its first connection as CONN 1, so the kicked ones are the even CONN numbers and the
left-alone ones the odd numbers from 3 up; kick.py prints each left-alone connection with its time and CONN number,
and `judge.py` pairs those with the RESULT lines by time and passes when every one has `got=25/25`. A reset after
the first connect fails the run. Retained switch commands fire `on_turn_on` only on the first connection, so
`switches_on` is not judged.
.agents/skills/hardware-test/reference/recipes/nrf52.md
+97
View File
@@ -4,3 +4,100 @@
Test config: the two LEDs as inverted GPIO outputs, the button as an inverted pull-up binary sensor, a
10 s alive interval. To retest the nrfutil download path, move the cached `sdk-nrf/nrfutil` aside first.
## ItsyBitsy over UF2 when serial DFU fails (#20481)
Serial DFU to the ItsyBitsy nRF52840 fails about half the time ("Target is not in DFU mode"). Reliable path: a
1200 baud touch on the app port, wait for the `ITSY840BOOT` volume, convert `zephyr/zephyr.hex` with the SDK's
`zephyr/scripts/build/uf2conv.py -f 0xADA52840 -c` and copy the .uf2 to the volume (the copy ends in an I/O error
when the board reboots, which is normal). macOS BLE scans give UUIDs, not MAC addresses.
## zephyr_ble_server connection slot under reordered callbacks (#21723)
`scripts/zephyr_ble_server`: the ItsyBitsy runs `server.yaml` (one connection slot) and an ESP32 runs `client.yaml`,
which connects, drops the link 300 ms later and reconnects as soon as the server advertises again. `run.sh NAME 90`
flashes the UF2, counts the server's `Connected`/`Disconnected`/`Advertising` lines and the client's connects,
and ends with PASS (more than one server connection) or FAIL; an empty capture or a silent client fails the setup.
- The connect and disconnect callbacks each `defer()` to the main loop and the bug needs the disconnect handled
first, which cannot be forced over the air. Force it with a test-only patch on both trees: replace the connect
callback's `defer(...)` with `set_timeout(5000, ...)`. A leaked reference then shows as one connection and nothing
after it (the dump still lists the closed link); a fixed build keeps cycling (17 in 90 s on #21723).
- `dfu: true` makes the next flash a 1200 baud touch; an app built without it needs a double tap on RESET. The
Zephyr app enumerates as `2fe3:0100`, the bootloader as `239a:0051`, so find the board by its USB serial number.
- macOS is a poor central here: it keeps old bonds with a board (`Peer removed pairing information` on connect)
and clearing them is a system setting. Use an ESP32 `ble_client`; the server's random static address comes from
its own log.
## SMP over UDP OTA over Thread, with reset faults (#17245, #21910)
Setup: a Thread border router (see openthread.md) whose OMR prefix the laptop routes to, and an ItsyBitsy nRF52840
(the Adafruit bootloader carries the MCUboot layout; the nRF52840 Dongle's Open DFU bootloader is rejected for
`zephyr_mcumgr` OTA). `scripts/smp_udp_ota/smp-udp-ota-dut.yaml` joins the network with `force_dataset: true` and
logs its build label every 10 s. The first image goes in over UF2, every later one with
`ota.sh MODE YAML VER ADDR` to the device's OMR address. A full image (about 380 KB) takes about 130 s.
- An ESP Thread Border Router board running ESPHome `openthread: border_router: rcp:` works as the border router
(pins in `boards.md`). Give both it and the device a fixed dataset with `force_dataset: true`; each keeps an old
stored dataset otherwise. The host learns the route to the OMR /64 from the border router's RA; ping the
device's OMR address before the first upload.
- Install the smpclient version pinned in requirements. An older one fails with `unexpected keyword argument
'timeout_s'` and a missing `get_max_cbor_and_data_size`, which looks like a PR bug. Check the version with the
Python of the venv that runs ESPHome, not a system pip.
- The build holds two `zephyr.uf2` files. Copy `.pioenvs/<name>/zephyr/zephyr.uf2` (the app, from 0x26000 up,
about 827 KB). `mcuboot/zephyr/zephyr.uf2` (about 70 KB) lands on the app slot and the board stops enumerating;
double tap RESET and copy the right one.
- To log the device's addresses, format `otIp6GetUnicastAddresses()` by hand: `network::IPAddress::str_to()`
does not link on nRF52 (no `inet_ntop`).
- A new image refuses the next upload (`No free slot. Testing mode but not confirmed yet.`) until it confirms itself.
Wait about 4 minutes between uploads.
- An image that is already in the secondary slot is only marked and reset (a few seconds). Change `ver` for every
upload that has to transfer, and expect a host-only change to rebuild byte-identical firmware.
- `inject.py` faults the reset on the host: `lostreply` drops the reply of a reset the device got, `lostreq` drops the
first request, `lostreq2` drops every reset. The device resets after a short delay, so even after a lost reply the
client usually still finds the old image running with the new one pending and resends the reset to the old image,
which is safe. `lostreq2` must end in an error with the old image still running. `ota.sh` ends with `check.sh`,
which prints PASS or FAIL for the mode, and `inject.py` fails the run when no reset was faulted.
- Without `libc_nano` the config overflows the 396,800 B slot by about 4 KB with Zephyr's TCP stack linked (about
11 KB of it, unused by SMP over UDP). With TCP left out (#21910) it fits with the full libc. A config with `api:`
keeps TCP.
- **The real OTA size limit is lower than the link limit.** The nRF Connect SDK partition manager overrides the device
tree, so read `partitions.yml` in the build directory, not `zephyr.dts`. On the ItsyBitsy layout `mcuboot_primary` is
0x61000 (97 sectors of 4 KB, 0x2f000 to 0x90000) and the app partition 0x60e00 (396,800 B); `mcuboot_secondary`
is 0x90000 to 0xf1000 and `settings_storage` 0xf2000 to 0xf4000. MCUboot swap using move keeps one sector for
its trailer and one for the move, so it only swaps in an image up to (97 - 1 - 1) × 4 KB = 389,120 B
(`app_max_sectors()` and `app_max_size()` in bootutil `swap_move.c`). An image between 389,120 and 396,800 B links,
uploads and the CLI reports `Successfully uploaded program`, but MCUboot never swaps it in: it stays pending in the
secondary slot, and every later upload and the SMP image erase fail with `NO_FREE_SLOT`. OTA stays stuck until
the slot is cleared over USB. Measured: 388,787 B swapped in, 392,155 B did not. `ota.sh` checks `app_update.bin`
against this limit with `mcuboot_slot.py limit` before it uploads, and afterwards asks the device which image runs
(`mcuboot_slot.py active`, by the image's SHA-256), since the CLI's exit code alone is not proof. That check passes once the
new image runs and says whether it has confirmed itself; add `--expect confirmed --wait 300` to prove it stays.
- With #17245 at 03d45d1aaa the build itself fails above the limit (`The application image is N bytes, but MCUboot
can only swap in L bytes on this board`), and after a confirmed reset the client waits for the device and logs
`runs the new image` or fails with `rebooted but did not swap in the new image`. After a dropped reset reply it still
ends with `The reboot of ... is not confirmed` without that wait, so `ota.sh`'s own image check is what proves those
runs.
- Clearing a stuck pending image: the SMP image erase is refused while the image is pending, and resets do not help.
Over USB, touch the app's CDC port at 1200 baud to enter the UF2 bootloader, then copy the 16-block UF2 from
`mcuboot_slot.py blank-uf2 BUILD OUT`, which writes 0xFF over the secondary slot's header page (`mcuboot_secondary`
in `partitions.yml`, 0x90000 on the ItsyBitsy). The bootloader resets on its own once the last block is written
(`cp` may report an I/O error then, which is normal), MCUboot finds no image header and clears the slot, and the
image states show slot 0 only.
- Over USB, the Adafruit UF2 bootloader only accepts blocks inside its app area (its `CURRENT.UF2` maps 0x1000 to
0xE9000). A UF2 with a block outside that area is never completed, and the bootloader then ignores every
later file, even a good app UF2, until a physical reset (double tap RESET or replug). Keep hand-made UF2 writes inside the app area.
- Results: https://github.com/esphome/esphome/pull/17245#issuecomment-6516152182,
https://github.com/esphome/esphome/pull/17245#issuecomment-6518292041 (swap limit),
https://github.com/esphome/esphome/pull/17245#issuecomment-6519010038 (retest)
## TCP stack only when a component uses TCP (#21910)
`scripts/nrf52_tcp_probe/tcp-probe.yaml` joins the test Thread network with no TCP user and opens a TCP and a UDP
socket twice from an interval. Build it per tree with `-s name NAME`, flash over UF2, capture the USB log, then
`check.sh BUILD CAPTURE`: it reads `CONFIG_NET_TCP` and the packet and buffer counts from
`.pioenvs/<name>/zephyr/zephyr/.config` and wants `tcp null udp ok` twice plus the `TCP stack not built` error exactly
once on a build without TCP, or `tcp ok udp ok` twice and no error with it. Add `api:` to see TCP and the larger pools
come back, and connect with `apicheck.py ADDR` over Thread. Measured on the ItsyBitsy: 12.9 KB less flash and 17.1 KB
less RAM without TCP (Zephyr's default pools, 16/16 instead of 24/48), and SMP over UDP OTA still works with them.
Results: https://github.com/esphome/esphome/pull/21910#issuecomment-6518287139
.agents/skills/hardware-test/reference/recipes/ota.md
+78
View File
@@ -6,3 +6,81 @@ All overlap orders (a web upload during a native OTA and the reverse) must be re
after an interrupted web upload waits about 14 s (ESP8266) or 7 s (ESP-IDF) for disconnect detection. A
refused web client on `web_server_idf` never gets the busy reply; the connection drops at reboot.
`pkill -f "a\|b"` does not alternate; use two pkills.
## OTA upload timing A/B (#21639, #21641, #21642)
`scripts/ota_timing/run.sh N PHASE...` times native OTA uploads per build (phase) and per board. It builds every
board from `TREE_<PHASE>`, does one warm-up upload per board (it installs the phase's build and is left out of the
results), checks over the API that each board reports the compile time from that build's `build_info.json`
(`apiinfo.py`), then runs N rounds of every mode on every board. Boards are interleaved per round so they share the
same air; put a nearby ESP32 on the same Wi-Fi in `BOARDS` as a network control. `summ.py` prints medians: never
judge from single runs, slow Wi-Fi gave 33 to 235 s for the same upload in one night.
- `otatime.py` drives `espota2.run_ota()` from the tree on `PYTHONPATH` and prints one `RESULT` line with the
`Update took` split, the compressed size, whether UDP was used and the time at each tenth of the upload.
An upload that leaves no `RESULT` line (board gone, script crash, timeout) is recorded as `rc: -1`, and `summ.py`
fails when a board and mode has fewer than N rows or an upload time cannot be read.
- Boards with an `api: encryption: key` also encrypt OTA: set `API_KEY` for `otatime.py` and `apiinfo.py`. LibreTiny
LN882H listens for OTA on 8820, not 8892; BK72xx and RTL87xx use 8892.
- Raw mode leaves `CLIENT_FEATURE_SUPPORTS_DEFLATE` out of the client's offer. Never switch deflate off after the
offer (`if deflate and 0:`): once the device accepted deflate it expects a deflate stream.
- `-tcp` modes make `espota2._loss_reason` return None, so the client asks to stay on TCP. Clearing
`CLIENT_FEATURE_SUPPORTS_UDP` instead desyncs the handshake (`receiving UDP token response: timed out`).
- LibreTiny trimmed UF2 (#21642): the CLI sends what `esphome.components.libretiny.uf2.device_ota_uf2()` returns for
`firmware.uf2`; that module only exists with #21642, so on older trees the full UF2 goes out. Compare the sizes
in the `Compressed to` lines, and rely on the API compile time check to show that the trimmed image booted.
`receiving chunk result: Unknown error from ESP` is error 0xFF sent by the device, not a dropped connection. The
device sends it for a decode or flash write error, and also when no data arrives for 105 s, so on a weak link it
usually means a stall. A failure about 105 s after the last progress, or the same error on a raw upload, points to
the link; to be sure, capture the device log (`Inflate err`, `Inflate overrun`, `No data received`).
Results: https://github.com/esphome/esphome/issues/21639#issuecomment-6409628227 (dev and LibreTiny 1.14.0 on a
CB3S), https://github.com/esphome/esphome/pull/21642#issuecomment-6412972562 (trimmed UF2 on CB3S, BK7238 and BW15),
https://github.com/esphome/esphome/pull/21641#issuecomment-6412976859 (new decoder on the same three).
## On-device inflate benchmark (#21639, #21641)
`scripts/ota_timing/inflate_bench`: `gen_streams.py NAME=IMAGE...` cuts a 128 KB slice from each image and writes
`bench_streams.hpp` with raw deflate streams (level 9, 4 KB and 32 KB windows). `bench.hpp` inflates every stream with
each ring size at least the encoder window, three times, and logs the best time plus input and output rates, then
`BENCHDONE`. `bench.sh CONFIG DEVICE` builds and uploads `bench-esp32s3.yaml` or `bench-bk72xx.yaml`, collects one pass
over syslog and fails when a case did not reach the end of its stream.
- LibreTiny defines `micros` as a macro, so the header calls `(esphome::micros)()`.
- Keep the streams near 130 KB on a BK7231N: an image with about 330 KB of extra incompressible data failed its
OTA with "Writing OTA data to flash memory failed". Use one image and `--windows 12` there.
- `bench.hpp` targets the decoder interface with `dest_limit`. #21641 drops it (the output runs into the window up
to `dest`); after that lands, remove the `dest_limit` line.
Results: https://github.com/esphome/esphome/issues/21639#issuecomment-6409786224
## Upload without a configuration (#21738)
`esphome upload --file IMAGE --device IP` with no YAML picks the OTA port from the image header and takes the password
from `--ota-password` or `ESPHOME_OTA_PASSWORD` and the key from `ESPHOME_OTA_KEY`. Test each chip family with its own
current image (`build/firmware.ota.bin` for ESP-IDF, `.pioenvs/<name>/firmware.bin` for ESP8266, `firmware.uf2` for
LibreTiny) and check the build over the API; switch one board between two builds to show a new image lands.
Point every case that should be refused before connecting at an unroutable address (192.0.2.1), never at a board: a
refusal prints no `Connecting to` line, and an image that slips through cannot reach a device. An ESP32-S3
`firmware.factory.bin` slipped through on 2026-10-27 (its bootloader header at offset 0 looks like an app), the device
reported `OTA successful` and its bootloader rejected the slot at boot; send the board its proper app image afterwards.
A factory image has the partition table magic `AA 50` at 0x8000 and the app at 0x10000.
## OTA automations on two OTA platforms (#21903)
`scripts/ota_automations/ota-automations-common.yaml` (a package) puts `esphome` and `web_server` OTA in one config,
each with all six automations (`on_begin`, `on_progress`, `on_end`, `on_abort`, `on_error`, `on_state_change`)
logging a platform tag and the argument. `run.sh esp32|esp8266 LABEL` builds, flashes by serial, and runs four cases
under one capture: a native upload, a native upload whose uploader is SIGKILLed after the first progress fire, a
web_server upload of a random 64 KB file and a web_server upload of the real image. `summ.py OUT_DIR` prints each
case's fires in order with progress collapsed to a count; diff dev against the PR.
- `web_server: ota: false` removes `/update` (404), so leave it out when the web platform is under test.
- A killed native uploader ends in `state 4` and `error 255`, not `abort`. `on_abort` only comes from a web upload
cut on the network. On ESP8266 those happen by themselves (1 in 4 uploads on dev), so count them on both builds with
`webrep.sh IP IMAGE COUNT` before blaming the PR.
- A random file through web_server gives `error 128` on the ESP32 and `error 132` on the ESP8266.
- A SIGTERM to the uploader lets it finish the transfer; use SIGKILL for the native error path.
- Results: https://github.com/esphome/esphome/pull/21903#issuecomment-6516529409
.agents/skills/hardware-test/reference/recipes/prometheus.md
+10
View File
@@ -0,0 +1,10 @@
# prometheus
## Date, time and datetime metrics (#9941)
`scripts/prometheus/prom-datetime.yaml` is a D1 mini with `web_server`, `prometheus` and three optimistic template
datetime entities; `prom-datetime-tz.yaml` adds an sntp time component with `HST10` (the zone applies without a sync).
`datetime_metrics.py HOST` prints the rows of `/metrics`, sets the entities over the API to 2040 values (past 2038 on
purpose) and prints them again with their UTC reading. Dates are local midnight in ms, times ms since midnight,
datetimes ms since the epoch, so a datetime set as an instant reads the same in both zones. It exits 1 when a time
or datetime row does not hold the value it set (dates depend on the zone and are only printed).
.agents/skills/hardware-test/reference/recipes/rs485_frame.md
+22
View File
@@ -0,0 +1,22 @@
# rs485_frame DLE/STX/ETX bus without a bus (#16758)
`scripts/rs485_frame`: an ESP32-C3 (logger on USB_SERIAL_JTAG) with the hub's UART on tx GPIO3 rx GPIO4 and a
simulated bus device on tx GPIO4 rx GPIO3, cross-wired through the GPIO matrix (`allow_other_uses: true` on all
four pins), 9600 baud, no wires. The simulator is polled from an `interval` and logs with the `sim` tag; the test
script logs with `hwt`.
- `simrs.hpp` builds sum16 big endian, header-inclusive frames (`10 00` stuffing, `10 10` with
`simrs::double_mode`) and logs each frame the hub sends (`RXF`) with start and end poll times, the silence since
the previous frame and the time since the simulator's own last byte. `rs-base.yaml` (board, cross-wired UARTs,
poll interval, the hub's CRC and a log line per received frame) and `buttons.yaml` are shared packages.
- Case files: `common.yaml` runs good / bad CRC / garbage / split at 25 and 150 ms / overlong / max length / two
frames in one write / a cut frame followed by a new DLE STX / a bad escape, then button presses that the hub must
hold until a `01 01` gate frame arrives (`replace_latest` keeps only the last press). `rsi2.yaml` (idle_gap gate),
`rsx.yaml` (fixed_delay gate), `rsd.yaml` (sniffer_only, double escape).
- `run.sh CASES LABEL [SECONDS]` (`CASES` is `common`, `rsi2`, `rsx` or `rsd`; `TREE`, `PORT`, `SC` in the
environment) writes a run file with its own name, builds and flashes with `esphome run --no-logs`, captures and
writes `out-rs<CASES><LABEL>.log` with time stamps and line numbers stripped. It fails without a `DONE` line or on
a crash. Diff the logs of dev and the PR; for the gate timing cases read the `RXF` lines (silence before each frame
the hub sent).
- On ESP32 at 9600 baud the default `rx_full_threshold` is 8, so a component does not see bus bytes for about 9 ms.
Queue a test frame at least 20 ms after the bus starts talking, or it collides on any idle-gap design.
.agents/skills/hardware-test/reference/recipes/scheduler.md
+15
View File
@@ -6,3 +6,18 @@ An external component whose template button arms an SDK `os_timer` (50 ms, one s
the callback runs in SYS context, records `millis()` and calls `set_timeout` or `defer`; the timeout
logs the elapsed time and loop count delta. Drive with an aioesphomeapi script (`subscribe_logs` plus
`button_command`). Build the same yaml twice with different names, one per tree.
## interval startup_delay and control from lambdas (#21799)
`scripts/interval/interval-common.yaml` has plain 1 s and 2.5 s intervals, a 1 s interval with `startup_delay: 5s`, a
3 s one with `startup_delay: 500ms`, and a 15 s control interval (`startup_delay: 0s`). The control interval
changes the plain 1 s interval to 500 ms with `id(i_plain).set_update_interval(500)` and `start_poller()`, then
stops it and the 5 s delayed one with `stop_poller()`. Every run logs `millis()`. `run.sh LABEL` flashes a D1 mini,
captures 40 s from boot and runs `ivsum.py`, which prints the run count, first run after boot and gaps per interval.
- Check that each delayed interval's first run comes at or after its delay, that the gaps equal the interval, that
the 500 ms change takes effect, and that nothing runs after a stop.
- The first run of an interval without a delay falls at a different time on every boot (the scheduler spreads first
runs), so do not compare those offsets between builds.
- `main.cpp` shows the class each interval gets (`IntervalTrigger` or `DelayedIntervalTrigger` on #21799).
- Results: https://github.com/esphome/esphome/pull/21799#issuecomment-6516798398
.agents/skills/hardware-test/reference/recipes/sensor_filters.md
+20
View File
@@ -0,0 +1,20 @@
# Sensor, binary_sensor and text_sensor filter A/B (#21831, #21813, #21830)
`scripts/sensor_filters` needs only a board. `sensors.yaml` holds 29 template sensors with every offset, multiply,
clamp, NTC, calibrate_linear, delta and lambda filter shape, plus a sensor with id `x` (a value lambda that reads an
id named `x`). `sf.yaml` adds binary and text sensor lambda filters and an interval that feeds the 50 inputs of
`sf.hpp` (NaN, ±inf, -0.0, values on and across the bounds) 200 ms apart, logging one line per input with every
filter output as float bits (`-` means dropped), then `DONE`.
- `run.sh esp8266|bk72xx LABEL` writes the per-run file, builds, flashes, captures and writes `out-sf<kind><LABEL>.out`
(100 lines). Compare a PR build with dev using `cmp`: identical files mean identical filter output, including
which values were dropped. ESP8266 matters because its float math is in software.
- The template sensor ids are `flt1`, `flt2` ...: `s8` and `s16` clash with ESP8266 SDK typedefs.
- Grep the build's `main.cpp` for the new code (for example `clamp_filter_value`, `delta_passes`, generated filter
functions) to prove the build came from the PR tree.
- `BASELINE` sets the delta baseline: a lambda works everywhere, a plain number crashed before #21811.
- Between boards the only difference is the sign of the NaN that `to_ntc_temperature` returns for 0 Ω (libm), on dev
too, so compare builds on the same board.
- The ESP8266 esptool stub can hit serial noise on a CH340 and the BK7238 link sometimes times out once; the runner
retries.
- Results: https://github.com/esphome/esphome/pull/21831#issuecomment-6490999545
.agents/skills/hardware-test/reference/recipes/sigma_delta.md
+36
View File
@@ -0,0 +1,36 @@
# sigma_delta speaker and rtttl sample taps
## Pulse density of the speaker pin, measured inside the chip (ESP32-P4, #18702)
Nothing is wired to the pin. `scripts/sigma_delta/sdprobe.hpp` calls `gpio_input_enable()` on the SDM output pin,
and a core 0 task reads it with `gpio_get_level()` 2000 times per window, with pseudo-random gaps of 0 to 255 cycles
(xorshift) that decorrelate the samples from the 1 MHz modulator. One window is about 2 ms and the density noise is
about 0.5% sd. The expected duty for an int8 density d is (d + 128) / 256, so 16-bit PCM at +50% reads 75%, 0 reads
50%, and full scale reads 99.6% or 0%.
The same header has:
- a core 0 feeder task (DC, sine, stereo L/R, a burst of N frames, any 8/16/24/32 bit mono or stereo format) that
calls `speaker->play(..., 20 ms)`;
- a played-frame counter on `add_audio_output_callback()`: frames per second over 4 s matches the rounding of the
10 MHz timer exactly;
- a CPU probe: a priority 10 task pinned to the loop core spins for 200 ms, and the iterations while playing against
idle give the interrupt share (44.1 kHz cost 20% of core 1).
`gen.py tpl.yaml > NAME.yaml` builds the whole sequence (the device name comes from `esphome -s name NAME`): DC levels,
volume, mute, formats, 2 Hz and 50 Hz sines with DUMP lines, sample rates, underrun, stop mid-play, finish, rtttl and a
play/stop hammer. `gen2.py` (both share the step helpers in `steps.py`) builds the inverted pin run (set the speaker
pin to `{number: GPIO21, inverted: true}` in a copy of `tpl.yaml`) plus the CPU cost per rate. `run.sh LABEL
[gen|gen2]` generates, builds, flashes, captures with `--ms` until `ALLDONE` and prints the `RES` lines; for `gen` it
then runs `an.py`, which fits the sines and prints the level edges of the underrun, stop and finish dumps. GPIO21 is
free on the Waveshare ESP32-P4 Module DEV KIT. Long operation warnings in the log come from the probe's own lambdas.
## rtttl click measurement (#22075)
`scripts/rtttl_edge_tap/edgetap.hpp`: `EdgeTap`, a pass-through `speaker::Speaker` that forwards to the real speaker
and reads the int16 samples rtttl writes. `rtttl.set_speaker()` it from a lambda, and call `sync()` from an
`interval: 10ms`, because `is_running()` and `is_stopped()` read the base class state. Use tunes with a rest between
every note, so a note is a run of samples between runs of 8 or more zeros. It logs each note's onset and release
level (the largest of the first or last 4 samples as a share of the note's peak): dev about 95%, the 32-sample fade
at most 12.5%. `rtttl-edge-tap-dut.yaml` is the AUX-2 config with a USB speaker as the mixer output (it needs the
AUX-2 package next to it, see [usb_audio.md](usb_audio.md)); `run.sh LABEL` plays eight tunes and prints the note
reports. Any speaker works the same way: wrap the one rtttl writes to.
.agents/skills/hardware-test/reference/recipes/sim_buses.md
+75
View File
@@ -0,0 +1,75 @@
# Simulated chips on the bus, fake Home Assistant, static buffers
`scripts/sim_buses/` and `scripts/static_buffer/`. Each header is added with `esphome: includes:` and wired in an
`on_boot` lambda, so no chip is needed. The wrappers take the real bus or SPI delegate and pass through every
address they do not simulate.
- `lcdsim.hpp`: `LcdSimBus`, an `i2c::I2CBus` wrapper that plays PCF8574 backpacks (P0 RS, P2 EN, P4 to P7 D4 to D7)
driving HD44780 controllers. It decodes the EN-strobed nibbles and rebuilds the rows written after each 0x80 and
0xC0 address command. `add()` up to three addresses, hand it to each `lcd_pcf8574` with `set_i2c_bus()` at
`on_boot` priority 800, and call `report()` from an interval. `lcd_an.py SERIAL` checks the rows against the
patterns its docstring lists (0x27 20x4, 0x26 16x2, 0x25 64x4), and fails on a display whose frame count does not
grow between its first and last report, on a segment longer than its rows or on
data past the 128 byte segment buffer, which the report counts as `overflow`, on a report from an address it does
not expect, or on any read (`reads`; the driver never reads, so the simulator NACKs them). A 64x4 display hangs the
code before #22331 in
setup.
- HT16K33: use `templates/i2c_fake/htfake.hpp` with its test runner (see [fake_i2c.md](fake_i2c.md)).
- `mxsim.hpp`: `MxSniff`, an `spi::SPIDelegate` in front of the real one that keeps what each MAX7219 in a chain
latches. Swap it in at `on_boot` priority 399 through `DelegatePeek::of(id(x))`:
`auto &d = DelegatePeek::of(id(x)); d = new MxSniff(d, chips);`. `mx_an.py SERIAL CHAIN...`
summarizes the reports, CHAIN being each name passed to `report()`, and fails on a named chain with no report line,
on malformed transactions (byte count not two per chip, or a partial byte from `write()` or
`write_cmd_addr_data()`, which are recorded and forwarded too), on a named chain with fewer than two report lines,
or a chain whose transaction count stays 0 or stops growing, and prints PASS otherwise.
- `spysim.hpp`: the same delegate trick (both headers carry `DelegatePeek`, so one config can include both), logging length and FNV-1a hash of every transaction over 1000 bytes (whole
frames, used for `pixoo`). `write()` and `write_cmd_addr_data()` are hashed and forwarded like `write_array()`;
a partial byte or a bus width other than 1 is hashed as whole bytes, so the SPY line carries `odd`, the count of
such transactions, and a dev vs PR hash match only holds when `odd` is 0 on both.
- `pisim.hpp`: drives two `packet_interface` stacks on cross-wired UARTs through `top()`, with payloads whose bytes
are a function of their index so every byte is checked, and the index and length each side sent (last 256) so a
truncated or split packet, or one whose slot a later index reused, counts as `rx_bad`. Send indices 0, 1, 2 and so
on from each side: a skipped index counts as `rx_lost` and an old or repeated one as `rx_bad`. `report(tag, true)` once both links are idle ends each
line in PASS only when that side received every packet the peer sent intact and the peer had no send refused;
`missing` is the rest, packets still in flight or lost at the tail. `packet_transport` drops packets carrying its own device
name, so a one-board test must use the layers directly.
- `hcsim.hpp`: a software SN74HC165 chain on ESP-IDF (data GPIO6, clock GPIO7, load GPIO10). A falling load edge
latches the pattern and each rising clock edge drives the next bit onto the data pad, which is in
`GPIO_MODE_INPUT_OUTPUT` so the component reads it from the same pin. Call `hcsim::report(label, loads0, clocks0)`
after each window with `hcsim::loads` and `hcsim::clocks` from its start; it logs `INVALID` instead of a result
when the GPIO or interrupt setup failed or the window saw no load or no clock edge, so a dead simulator cannot pass
as a wrong but steady pattern.
- `ledprobe.hpp`: samples a status LED (or any output) pin every 2 ms from an `esp_timer`, off the loop task, and
prints blink count, on time, period and the longest gap per window. It measures `status_led` while the loop is
blocked (#16407). Pass `ledprobe::n` from the window start as the mark; a window with more than 400 edges logs
`INVALID` and no result line instead of passing for a stalled LED. So does every window when the pin or timer
setup failed or the timer has not sampled for 100 ms, so a dead probe cannot read as a quiet LED.
- `fakeha.py HOST OUT_PREFIX`: an aioesphomeapi client standing in for Home Assistant for `homeassistant` select
mirrors. It answers state subscriptions from a table, pushes option and state changes (full, overfull, quoted,
unparseable), checks each step through a "Dump" button, captures the action calls, churns 600 option updates
while watching the heap, and checks the entity options after a reconnect. A step fails when either DUMP line is
missing, and a rejected update also needs the device's rejection log line, so an update that never arrived cannot
pass. Exits 1 on a failed step and prints PASS otherwise.
- `wizard_drive.py HOST`: finishes the device wizard through aioesphomeapi 46.28 (`device_wizard`,
`wizard_input_set`), answers the subscriptions the inputs create and checks the values reached the entities.
## Static buffers (`cg.static_buffer`)
`scripts/static_buffer/` holds two local external components and `static-buffer-dut.yaml`, which loads them:
- `sbtest` allocates three buffers with `cg.static_buffer` (37 `uint8_t`, 5 `uint32_t`, and `const char *` sized by
a C++ expression) and checks at setup that they are zeroed and aligned, then fills each completely; at
`dump_config()` it checks no other instance's fill reached them. Two instances prove the buffers are distinct.
Both `SBTEST` lines end in `PASS` or `FAIL`; the `dump_config()` one passes only when the setup checks passed too.
- `sbpsram` asks for `psram=True` and uses the pointer codegen hands it: the static buffer without PSRAM, or a
zeroed `psram_buffer<T>()` with a `psram:` block, which logs `external=1` (nullptr if the allocation failed).
It also gets a plain 8 word `uint32_t` static buffer, which must be non-null, aligned and zeroed at start and read
back its fill (`plain=1`). Its `dump_config()` line ends in `PASS` only when both readbacks match, both buffers
were zeroed at start and, with PSRAM, the PSRAM one is in external RAM.
## Gotchas
- Some "classic" devkits with a CP2102N carry an ESP32-PICO-D4. GPIO16 and GPIO17 are its flash pins, and an
ESP-IDF build that drives them hits the interrupt watchdog. Use `board: pico32` and GPIO9/GPIO10.
- An `addressable_light` display writes nothing until its light is turned on.
- Before calling a rebased PR's change trivial, diff the PR's own diff (head against its parent) old against new: a
move that looks like a merge only can carry real commits from below.
.agents/skills/hardware-test/reference/recipes/speaker.md
+43
View File
@@ -17,3 +17,46 @@ only, announcement all four, after stop none, every cycle. API commands land a s
the probe against the `State changed to` lines rather than the driver's timestamps. Internal free heap after a stop
moved by 2.5 kB between two boots of the same build, so a heap delta needs more than one boot per build. Results:
https://github.com/esphome/esphome/pull/21203#issuecomment-6299581943
## Streamed TTS with a pause (#21090, #21091)
Home Assistant streams TTS while it is still being generated, so the player must start on the first part instead of
waiting for the whole file. `scripts/speaker_tts_pause/`:
- `mk.py INTRO_AUDIO CONT_AUDIO www/s1.flac` builds one 48 kHz mono FLAC stream (the intro padded to a 4096-sample
frame boundary, then the continuation) and writes the byte offset of the split to `s1.flac.cut`. Make the intro
with any TTS, e.g. `say -o intro.aiff "..."` on macOS; build a short one (`s1`) and a long one (`s2`).
- `srv.py PORT www` serves the file chunked: the header and intro at once, then it holds the connection open for
`PAUSE` seconds (8), then the rest.
- `tts-common.yaml` swaps the AUX-2's `speaker_source` player for the `speaker` platform player and counts played
frames with `add_audio_output_callback` on both resampler speakers into the counters in `frames.h` (one `[frames`
log line per change, read over serial with `--ms`). Its `on_boot` must be a list entry: a dict `on_boot` replaces
the package's list and the AUX-2 never starts Wi-Fi or Ethernet.
- `run.sh LABEL=TREE...` flashes each build and drives two short-intro and two long-intro announcements and one
media play through `scripts/speaker_media_player/drive.py` (set `DRIVE` when running from a scratch copy); `an.py`
prints first audio, the server's send times and how much of the intro played before the rest arrived, per request.
A request fails when it never played the whole intro or stopped short of 95 % of the stream.
Before the two PRs the player waited for the rest of the stream (8.2 s) for both a 22.5 KB and a 50 KB intro; with
both it starts at about 1 s.
## Voice PE wake word audio (#21885)
`scripts/voice_wake_word_audio/va.py HOST KEY OUTDIR accept,reject,timeout` stands in for Home Assistant
(aioesphomeapi 46.27.0 or later, `wake_word_audio=True`), answers each run by mode and saves both channels as WAV;
`locate.py OUTDIR` finds the played phrase in them by envelope cross-correlation against `wake16k.wav`.
`run.sh HOST TAG [ROUNDS]` runs reject and timeout rounds while playing the phrase every 9 s, starting once `va.py`
is READY. `va.py` fails a START before READY or during a run, and `run.sh`, `stale.py` and `mww.py` fail at once
when the player fails or hangs for 30 s.
- Give the test build its own API key so Home Assistant cannot hold the voice assistant subscription.
- Make the phrase with any TTS (`say -o wake.aiff "Okay Nabu"`, then `ffmpeg -i wake.aiff -ac 1 -ar 16000
wake16k.wav`) and play it from the host near the device (`PLAY`, default `afplay`). On macOS the terminal needs
audio permission first; before that `afplay` hangs.
- The PE mute switch only mutes samples. To stop microWakeWord, add `mww-buttons.yaml` (template buttons calling
`micro_wake_word.stop` and `start`); `mww.py` checks that no run starts while it is stopped.
- Stale clip check: `stale.py` says a spoken marker word (`marker.aiff`), stops microWakeWord for 3 s, starts it and
says the wake word; `stalean.py` measures loud audio before the phrase in each clip and exits 1 above
`MAX_LOUD_MS` (default 100). The loud level has no default: calibrate `LOUD_LEVEL` on each setup from the phrase
and pre-phrase peaks it prints (a run without it prints them and fails), somewhere between room noise and the
marker's peak. A trial whose phrase peak is under twice `LOUD_LEVEL` fails as too quiet to judge. A steady 1 kHz
beep never reaches the PE stream (the XMOS processing removes it), so the marker has to be speech.
.agents/skills/hardware-test/reference/recipes/sun.md
+19
View File
@@ -0,0 +1,19 @@
# sun on_sunrise and on_sunset without waiting for the sun (#21803)
`scripts/sun/sun-common.yaml` (a package) puts the observer on the equator and, once SNTP has synced, searches the
longitudes for one where the sun stands near -5° and rises as the observer moves east. It holds that longitude for
one 60 s elevation poll first: the poll before saw the sun at longitude 0, and the jump could read as a crossing.
Crossings until then are logged as `crossing before the sweep ignored` and not counted. An interval then moves the
longitude by 0.125° every 5 s, which sweeps the elevation from -5° to +6° and back at about 1.5° a minute, reversing
above +6° and below -5°. Five triggers (sunrise at the default, 2° and 4°, sunset at the default and -2°) fire from
the real 60 s elevation poll; each logs the elevation it fired at and counts in `fires`, logged every 30 s.
- The sweep stops after one full pass and logs `sweep done`. `run.sh esp32|esp8266 LABEL` builds, flashes and
captures up to 20 minutes (a pass takes about 17), then `check.py` wants `sweep done` and the counter at 5 with no
trigger firing twice. Run dev and the PR on the same board; two boards can run in parallel.
- At 1.5° a minute a crossing fires up to about 1.7° past its elevation, one poll late at most.
- The seconds past the minute of the fire lines show the poll phase: separate pollers fire at different seconds,
one shared poll fires every trigger in the same second.
- `id(sun_id)` is a pointer in lambdas (`->`). Judge by the `fires` counter: the classic devkit's serial log can
garble single lines.
- Results: https://github.com/esphome/esphome/pull/21803#issuecomment-6490173072
.agents/skills/hardware-test/reference/recipes/twai_self.md
+24
View File
@@ -0,0 +1,24 @@
# CAN (esp32_can) without a transceiver (#21792, #21795)
`scripts/twai_self`: `esp32_can` with `mode: NO_ACK`, TX on GPIO25 and RX on GPIO26. After boot `canself.hpp` enables
the input on GPIO25 and routes it to the controller's receive signal (`esp_rom_gpio_connect_in_signal(25,
TWAI_RX_IDX, false)`), so the controller hears its own transmit pad. Frames go out with `twai_transmit_v2` and
`TWAI_MSG_FLAG_SELF` (the driver handle is reached through explicit template instantiation), so every frame runs
through the normal receive path and `on_frame`.
- `can.yaml` has nine `on_frame` entries (standard and extended ids, masks, remote-only and data-only filters, two
entries with the same filter, an id with bits outside its mask that must never fire) and sends 20 rounds of 7
frames. `run.sh LABEL` writes `out-can<LABEL>.counts` (fires per trigger, id, flags and data); diff dev and the PR.
- Set `rx_queue_len: 32`: with the default 5, a burst of 7 frames loses the last two most of the time, on every
build.
- ESPHome's own `canbus.send` does not set the self flag, so its frames are not received in this setup.
- Results: https://github.com/esphome/esphome/pull/21795#issuecomment-6491777381
## ESP32-C3 and extra frame shapes (#21950)
The C3 works the same way: `variant: esp32c3`, TX GPIO5 and RX GPIO6, `TX_PAD = GPIO_NUM_5` in `canself.hpp`, and
the logger on USB_SERIAL_JTAG. `canx.hpp` adds a classic frame with DLC 12 (`TWAI_MSG_FLAG_DLC_NON_COMP`), the
`send_data` overloads (standard, extended, remote, empty, a 10-byte payload that must be clamped, a vector) and a
`twai_get_status_info_v2` dump before and after (`canx::tx_status(id(can0), "before")`). The `get()` that reads the
private handle is a friend found only by argument-dependent lookup: call `get(canself::Handle{})`, never
`canself::get(...)`.
.agents/skills/hardware-test/reference/recipes/uart_sim.md
+57 -2
View File
@@ -15,5 +15,60 @@ packages; copy them with a different name (`frabase` and so on) for the base bui
- Polled readers: run `update()` from a script and log `micros()` around it to measure blocking
(sm300d2 on dev blocks about 104 ms on an empty buffer).
- The logger stays on UART0, so three builds cover five components. Drive with `scripts/uart_sim/frdrive.py HOST
LOG press:NAME sel:NAME=OPT num:NAME=V wait:S`, or `scripts/uart_sim/run.sh NAME TREE SECONDS OPS...` (build
and flash from TREE with `esphome run --no-logs`, capture, drive; `PORT` and `SC` in the environment).
LOG press:NAME sel:NAME=OPT num:NAME=V wait:S @FILE` (`@FILE` reads one op per line), or
`scripts/uart_sim/run.sh NAME TREE SECONDS OPS...` (build and flash from TREE with `esphome run --no-logs`,
capture, drive; `PORT` and `SC` in the environment, `ERASE=1` erases the flash first, `DRIVER` picks another
API driver).
## Particulate sensors: gcja5, pm1006, sds011 (#21939)
`templates/uart_sim/pmsim.hpp` adds frame builders `sim::gcja5`, `sim::pm1006` and `sim::sds011`, each with a bad
checksum or bad end flag. `fp-parts.yaml` puts gcja5 on UART1 (9600 8E1, with a template binary sensor that shows
`status_has_warning()`) and pm1006 on UART2; `fs-parts.yaml` has sds011 alone. Write the run files the same way as
`fra.yaml` (`fp.yaml`, `fs.yaml` with their own name).
- Every button injects one case with its own PM value, so each published state names its case: good, two frames,
bad checksum, end or tail, garbage before a frame, a cut-off frame followed by a good one, a repeated first header
byte, and splits of 300 and 700 ms (either side of the 500 ms gap reset).
- `run.sh NAME TREE 150 @fp-ops.txt` runs the op list from the file; `fs-ops.txt`, `fd-ops.txt` and `fj-ops.txt`
are the other lists.
- The loopback also feeds each component its own writes (pm1006 request, sds011 setup and sleep/work commands),
which must not disturb the next frame.
- The API coalesces two states published in the same loop pass, so "two frames" shows only the second value.
- Found with it: on dev gcja5 published bad and misaligned frames as readings (268435456).
## 4-byte distance sensors: a01nyub, a02yyuw, jsn_sr04t (#21948)
`sim::ds1603l(mm, bad_ck)` builds the same `FF H L sum` frame; `fd-parts.yaml` (a01nyub on UART1, a02yyuw on UART2) and `fj-parts.yaml`
(jsn_sr04t, polled every 15 s), with the same case list as above plus a reading below the minimum distance. With
loopback the jsn_sr04t request byte `55` can land inside a split frame and break it; check the `Request read out`
timestamps before calling a difference between builds.
## LD6002B TinyFrame parser (#19836, #19837)
`templates/uart_sim/ld6002b/`: `ld6sim.hpp` is a fake module on a UART cross-wired to the component's UART (UART1
tx 25 rx 26, UART2 tx 26 rx 25), set up by the shared `ld6-base.yaml` package. It ACKs every command with an empty
frame of the same type and logs the bytes it received (`MOD RX`), so the bytes on the wire can be diffed between
builds. Target reports carry a distinct X per
case, and `T1 X` shows which frames got through.
- `ld6-parser-cases.yaml` (used by `ld6-common.yaml`, which turns the query answers off): good, byte by byte (one
byte per poll, so the component's loop runs in between), garbage before a frame, bad and lost header or data
checksums, an oversized payload, a burst of 20. The script runs by itself from `on_boot`; `ld6p.yaml` is the run file
(copy it with another name for the base build). `run.sh NAME TREE` builds, flashes over serial and captures,
and fails without a `CASE done` line.
- Garbage that contains `01` right before a frame loses that frame on dev and on the PR (a false header, no rescan).
- Full component A/B: `ld6sim.hpp` also answers every query with a fixed report (delay, sensitivity, trigger,
installation, Z range, low power, low power sleep, both area reports, version); `ld6x-common.yaml` has the full
entity set and runs the parser cases too (`ld6x.yaml` is its run file); `ld6drive.py HOST` presses every button,
sets every number and select and toggles every switch over the API. Run it with `ERASE=1 DRIVER=ld6drive.py
scripts/uart_sim/run.sh NAME TREE 100`: switch and select states and the area id are stored preferences, and a previous build's run changes the
next build's boot state.
- `m4-common.yaml` and `m5-common.yaml` run the same fake against `ld6004`: target and area reports, work status and
radar on/off reports, malformed reports, and the point cloud and target display switches across a reboot
(`m5` reboots once and checks the restored switch states). `m4.yaml` and `m5.yaml` are the run files, and like
`ld6p.yaml` each can be copied with another name for the base build. Run m5 with `ERASE=1 run.sh NAME TREE 75`: the boot
counter and switch states are stored preferences that survive a flash, and the second boot's `CASE done` comes
about 49 s after reset. Only the second boot logs `CASE done`, so a skipped reboot fails the run.
See `rs485_frame.md` for the same cross-wired UART trick on an ESP32-C3.
.agents/skills/hardware-test/reference/recipes/value_range.md
+15
View File
@@ -0,0 +1,15 @@
# sensor and number on_value_range A/B (#21814, #21817, #21818)
`scripts/value_range/value-range-common.yaml` (a package) has one template sensor with seven triggers (constant
bounds, one-sided, a lambda bound on `x`, a bound from another sensor's state that stays NaN until step 22, both
bounds NaN, and an identical twin) and one template number with three triggers. It feeds them 30 values 200 ms apart
(on the bounds, just past them, repeats, NaN, ±inf, a moving bound), then syncs preferences and restarts, then
sends 50, 95 and 50 to check the restored in-range flag. Every fire logs its step and `x`.
- `run.sh bk72xx|esp8266|esp32 LABEL` writes the per-build file with a fresh `tag`, builds, flashes, captures 90 s
(through the restart) and writes `out-rng<kind><LABEL>.seq`; diff dev against each PR head.
- The sequence primes every trigger first (bound 0, value -500, bound NaN): the in-range flags are stored in flash,
so without priming a fresh build starts from whatever the previous run left, and the first fires differ.
- The phase global resets when `tag` changes, so each reflash runs the whole sequence.
- Log line numbers differ between trees; the runner strips them before writing the `.seq` file.
- Results: https://github.com/esphome/esphome/pull/21818#issuecomment-6491846503
.agents/skills/hardware-test/reference/recipes/voice_assistant.md
+15
View File
@@ -0,0 +1,15 @@
# voice_assistant
## Voice PE late TTS start (#19408)
Only the subscribed client (Home Assistant) may send `VoiceAssistantAnnounceRequest`, so both builds carry
`scripts/voice_announce/slow-announce.yaml`, a template button that calls `id(va).on_announce(msg)` with
`start_conversation = true` and a URL on the host. `drive.py HOST KEY DELAY OUT` serves a FLAC (WAV as `audio/wav`
is rejected by micro_decoder) only after DELAY seconds, presses the button and timestamps the device logs. It
holds the voice assistant subscription throughout, since without a subscriber the device drops the announcement
state at once. It imports `va_common.py` from `scripts/voice_wake_word_audio/`, so keep the two directories side
by side.
`run.sh DEVICE LABEL=CONFIG=TREE...` builds, OTAs and runs both builds twice. The player gives up after 6 header
attempts of 5 s.
The wake word audio flow is in [`speaker.md`](speaker.md).
.agents/skills/hardware-test/reference/recipes/web_server.md
+8 -7
View File
@@ -12,13 +12,14 @@ on ESP32. Keep `power_save_mode: none`, and drive the device by address: mDNS na
`scripts/web_server/sse.py HOST SECONDS [--clients N] [--stall] [--churn CYCLES]` opens raw TCP connections to
`/events`, decodes the chunked body and parses every `state` event as JSON; `--stall` adds a connection with a 2 kB
receive buffer that never reads (the device must log `Closing stuck EventSource connection` after the 20 s stall
timeout), `--churn` opens and resets a connection CYCLES times. `sse_cases.sh HOST KEY LABEL CAPTURE` runs the
set: 1 client 60 s, 4 clients 60 s, a reader plus a stalled client 45 s, a reader plus 10 abrupt closes, then two
clients with the "Burst" button (50 sensor and 50 text publishes in one loop pass). Pass: 0 invalid JSON on every
client, the oversize sensor dropped with its warning on every publish, the stalled session closed after about
20 s, no reset. The loop task watermark is a minimum since boot, so compare the value after the first client, after
four clients and after the burst between the builds (the SSE split in #21109 left 1280 B more on the ESP32 classic).
receive buffer that never reads (the device must log `Closing stuck stream` on ESP-IDF and `Closing stuck
EventSource connection` elsewhere, after the 20 s stall timeout), `--churn` opens and resets a connection CYCLES
times. `sse_cases.sh HOST KEY LABEL CAPTURE` runs the set: 1 client 60 s, 4 clients 60 s, a reader plus a stalled
client 45 s, a reader plus 10 abrupt closes, then two clients with the "Burst" button (50 sensor and 50 text
publishes in one loop pass). Pass: 0 invalid JSON on every client, the oversize sensor dropped with its warning on
every publish, the stalled session closed after about 20 s, no reset. The loop task watermark is a minimum since
boot, so compare the value after the first client, after four clients and after the burst between the builds (the
SSE split in #21109 left 1280 B more on the ESP32 classic).
For the HTTPD task, `web_server: auth: type: digest` (the default `auth` is Basic) and
`scripts/web_server/httpd_cases.sh HOST USER PASS LABEL CAPTURE`: `httpmix.sh` sends a `curl --anyauth` request
.agents/skills/hardware-test/reference/recipes/wifi.md
+56
View File
@@ -37,3 +37,59 @@ AP start (the fix in that PR), the first AP start failed on every boot with `esp
(DHCP server already started by the AP start event) and `Failed to enable NAT`, and the bridge only came up on the
retry 90 s later; a client that cannot find the SSID for the first minute on an older build is that. With the fix
the bridge is up 6 s after boot. Any change to the ESP-IDF AP start should also rerun the captive portal hammer.
## Reboot against a WPA2/WPA3 PMF access point (#21590)
- AP: `scripts/wpa3_ap/wdap.yaml` on a classic devkit. ESPHome `wifi: ap:` only, then an on_boot lambda switches it
to `WIFI_AUTH_WPA2_WPA3_PSK`, PMF capable, and registers a WIFI_EVENT handler that logs `STA JOIN` and
`STA LEAVE ... reason N` (the include header pulls in `esp_wifi.h`). It disables Wi-Fi after 420 s.
- AP leave reason 3 means the station sent a deauth; reason 2 means the AP found a stale association when the
station came back; several reason 2 before one join are rejected reconnects.
- DUTs (`wdbk.yaml` BK7238, `wdcb.yaml` CB3S, both on `wd-common.yaml`) list the AP at priority 10 and the main
network at 0, and reboot 30 s after joining the AP and 150 s after joining the main network. So they move to the
AP while it is up and fall back to the main network (where they can be flashed over the air) once its window
ends. `run.sh BUILD` flashes the AP, does OTA for the CB3S and a serial flash for the BK7238, then captures one AP
window; `an.py` prints each station's join and leave sequence and fails on a rejected reconnect, an AP that did
not switch to WPA2/WPA3 (`AP CONFIG FAILED`), a DUT missing from the AP events (`DUT_MACS`) or a BK7238 that never
joined the AP.
- Gotchas: the LibreTiny build directory has two `.uf2` files, so flash `firmware.uf2`. The BK7238 serial flash
sometimes fails to link while the chip is in a reboot loop; retry it 3 or 4 times. OTA fails if the DUT reboots
mid-upload; retry.
- Finding: BDK 3.0.78 rejects about 2 reconnects per reboot when the station left without a deauth; BDK 3.0.33
does not.
## WISP and ALWAYS_ON AP rig (#20077)
`scripts/wisp_ap`: the upstream is an ESP32-S3 with Ethernet running a WISP bridge (`wisp-upstream.yaml`) with its AP on
10.40.0.1/24 and web buttons `ap off` and `ap on`. Its subnet must not be 192.168.4.0/24, the DUT AP's default, or
nothing routes. The DUT is a classic devkit (`dut-wisp.yaml` or `dut-always-on.yaml`); the client is a D1 mini on
the DUT's AP (`wispcli.yaml`) logging its DNS server, a name lookup, a GET by name, the AP itself and a LAN file by
IP. `run.sh DUT START SECONDS T:STATE...` switches the upstream AP at the given times and `sum.py` groups the client
results by phase. Capture the D1 mini without `--reset` (a CH340 floods garbage after an RTS reset). Clients keep
the captive portal's DNS answer for its TTL.
## AP restart with WPA3 mixed and LIGHT power save (#21531)
`scripts/wifi_restart`: the WISP upstream (`wisp-upstream-wpa3.yaml`) switched to WPA2/WPA3 mixed by a script that
runs again after every `ap on`, DUTs (`rebk.yaml`, `recb.yaml` on `re-common.yaml`) with a static IP on the bridge's
subnet, a fallback AP, `power_save_mode: LIGHT` and syslog to the host through the NAT. `run.sh BUILD` switches the
AP off and on three times; `an.py` fails on a reboot, a crash or a DUT that is not back on syslog within 120 s of an
AP start. After 19 minutes the DUTs run `wifi.configure` to the main network; that keeps the static IP, so the next
OTA needs the host to have an address on the bridge's subnet as well (an interface alias). The CB3S log is on UART1
(TX1), so its configs need `logger: hardware_uart: UART1`. Runners must `pkill` only their own ports; a global pkill
stops the other runs' captures.
## Channel and network switching with a bench AP (#22142)
`scripts/wifi_channel/`: `bench-ap.yaml` makes an ESP32-S3 an AP-only bench network on a fixed channel (11 by
default; pick one your normal network does not use), and `dut-common.yaml` gives the device under test that AP at
priority 10 plus your normal network, logs every `wifi_info` ssid and channel update (with the channel the component
reports and whether it is connected), and cycles `wifi.disable` and `wifi.enable` every 90 s. `run.sh LABEL` (env
`TREE`, `PORT`, `AP_PORT`, `SC`, `PY`, and `BENCH_CHANNEL` when the AP is not on 11) flashes the device and captures 420 s while it takes the AP down with
`esptool --port <AP port> --after no-reset chip_id` (the board stays in the bootloader) and back with
`--after hard-reset`. The channel sensor must follow every move between the two networks: the run passes when the
connected channel starts and ends on the bench channel with another channel in between.
- Dropping the AP under a connected device gives a `Beacon Timeout` link loss.
- The 90 s interval fires once right after boot.
- A `Disconnected ... Association Leave` right after `Connecting to` is the aborted attempt, not a missed connect.
.agents/skills/hardware-test/reference/recipes/xiaomi_ble.md
+38
View File
@@ -0,0 +1,38 @@
# Xiaomi BLE
## Xiaomi, ATC and PVVX parsing without the sensors (#21483)
No Xiaomi devices are needed, and one ESP32 cannot hear its own advertising, so the frames are injected into the
tracker as scan results: everything after the radio runs as normal.
- `scripts/xiaomi_ble/gen.py` writes `frames.hpp` and `expected.json`: plain MiBeacon (0x50), encrypted v5 23 byte
with MAC and 19 byte without, real AES-CCM (`cryptography` AESCCM, tag 4, AAD 0x11, nonce = MAC reversed + pid +
cnt + 3 byte ext counter), ATC (13 byte, big endian) and PVVX (15 byte, little endian) 0x181A frames, a corrupted
tag every other cycle and a counter 0 boot frame. It models the old shared duplicate counter (`base`) and the per
device one (`pr`) and prints the expected publish counts.
- `xbinject.yaml` (ESP-IDF devkit) includes `frames.hpp`; an `interval:` builds a `BLEScanResult` and calls
`global_esp32_ble_tracker->gap_scan_event_handler(r)`. `count.py` counts the `Got Xiaomi` blocks (sensor
publishes are not logged at DEBUG) and compares them with `expected.json`.
- On ESP32 the tracker's own triggers sit in `listeners_`, which runs before `neutral_listeners_` (the
ble_device_base devices), so an `on_ble_service_data_advertise` never sees what a Xiaomi listener did to the
shared data. Check that directly: `xb_rewrite_probe(id(xa))` builds an `ESPBTDevice` with `parse_scan_rst()`,
calls the component's `parse_device()` and logs the service data before and after (`[probe` lines).
- `run.sh inject pr|base` builds, flashes, captures and prints PASS when the counts match that build's model and,
on the PR build, the probe's service data is the same before and after `parse_device()`.
Base dropped a second device's frame with the same counter, the frame after a bad tag and a first frame with
counter 0, and rewrote the shared data in place; the PR fixed all of them.
## Over the air with a second ESP32
- Advertiser: an ESP32-S3 with Ethernet (OTA over Ethernet), `xbadv.yaml` with `adv_frames.hpp` from
`gen.py --ota`. Per frame: stop advertising, `esp_ble_gap_set_rand_addr`, `config_adv_data_raw`, start
non-connectable advertising with `own_addr_type` random, 20 ms interval, 250 ms dwell. Random static addresses
need the top two bits set, so these use C4:C1:38 instead of A4. `esp32_ble:` alone brings up the stack. The
web_server button starts a run: `curl -X POST -d "" http://<advertiser>/button/start/press` (no body gives 411).
Its `failed sends` sensor counts only GAP calls rejected when queued; a frame the controller drops later shows
up as missing publishes in `count.py`, the same as radio loss.
- Receiver: `xbrecv.yaml` on the devkit, passive scan with window = interval = 100 ms. `run.sh ota pr|base` (with
`ADV` set) flashes it, resets it with a capture and presses start 18 s later, so the counter 0 boot frame is the
first one it hears.
- Each frame arrives about 4 times; the counts matched the injection run exactly apart from one radio loss, so the
over the air comparison allows two missing publishes per tag.
.agents/skills/hardware-test/scripts/.gitignore
+23
View File
@@ -0,0 +1,23 @@
# Run artifacts the runners write next to their scripts; none of these patterns match a tracked file.
out-*/
out-*.*
.esphome/
secrets.yaml
__pycache__/
ble_adv_triggers/rxbk72xx*.yaml
ble_adv_triggers/rxesp32*.yaml
ezo_fake_bus/ezo?*.yaml
homeassistant_button/habtn*.yaml
hub_input_sim/hubsim*.yaml
interval/ivl*.yaml
led_driver_sniff/led*.yaml
ota_automations/otaauto*.yaml
output_button/outbtn*.yaml
remote_base/rb*.yaml
sensor_filters/sf?*.yaml
sun/sunesp*.yaml
twai_self/can?*.yaml
uart_button/uartbtn*.yaml
value_range/rng*.yaml
ld2420_sim/ldenergy*.yaml
ld2420_sim/ldsimple*.yaml
.agents/skills/hardware-test/scripts/apiconn.py
+60
View File
@@ -0,0 +1,60 @@
"""Shared helpers for the API drivers: connect with retries, and the text of an API log line.
Import it with this directory on sys.path (the drivers add their parent directory, runners set PYTHONPATH).
"""
import asyncio
import contextlib
import os
import re
import sys
from aioesphomeapi import (
APIClient,
EncryptionPlaintextAPIError,
InvalidAuthAPIError,
InvalidEncryptionKeyAPIError,
RequiresEncryptionAPIError,
)
ANSI = re.compile(r"\x1b\[[0-9;]*[A-Za-z]")
# a wrong key or a plaintext/Noise mismatch does not go away with a retry
FATAL = (
EncryptionPlaintextAPIError,
InvalidAuthAPIError,
InvalidEncryptionKeyAPIError,
RequiresEncryptionAPIError,
)
async def connect(host: str, tries: int = 30, timeout: float = 10) -> APIClient:
"""Connect and log in, retrying once a second; exits after TRIES failures with the last error.
API_KEY in the env selects Noise; unset, empty or - is plaintext.
"""
key = os.environ.get("API_KEY")
last: BaseException | None = None
for _ in range(tries):
c = APIClient(
host, 6053, None, noise_psk=None if key in (None, "", "-") else key
)
try:
await asyncio.wait_for(c.connect(login=True), timeout)
except FATAL as e:
sys.exit(f"no API connection to {host}: {type(e).__name__}: {e}")
except Exception as e: # noqa: BLE001
last = e
# release the half-open socket so retries do not use up the device's API slots
with contextlib.suppress(Exception):
await c.disconnect(force=True)
await asyncio.sleep(1)
else:
return c
sys.exit(
f"no API connection to {host} after {tries} tries: {type(last).__name__}: {last}"
)
def log_text(msg) -> str:
"""The message of a subscribe_logs callback as text, without ANSI colour codes."""
return ANSI.sub("", msg.message.decode(errors="replace"))
.agents/skills/hardware-test/scripts/automation_trace/automation-trace-common.yaml
+348
View File
@@ -0,0 +1,348 @@
# Automation code generation trace: every step logs a marker "M <case> <values>". A package: the per-run file from
# run.sh supplies the board, Wi-Fi and name. drive.py records the markers over the API.
logger:
level: DEBUG
api:
reboot_timeout: 0s
ota:
- platform: esphome
globals:
- {id: g_a, type: int, initial_value: "0"}
- {id: g_b, type: int, initial_value: "0"}
- {id: g_tick, type: int, initial_value: "0"}
- {id: g_ticking, type: bool, initial_value: "false"}
- {id: g_par, type: int, initial_value: "0"}
- {id: g_par3, type: int, initial_value: "0"}
- {id: g_par4, type: int, initial_value: "0"}
interval:
- interval: 100ms
then:
- if:
condition:
lambda: return id(g_ticking);
then:
- lambda: id(g_tick)++;
number:
- platform: template
id: num
name: Num
optimistic: true
min_value: 0
max_value: 100
step: 1
on_value:
- logger.log: {format: "M num_on_value %.0f", args: [x]}
- if:
condition:
lambda: return x > 50;
then:
- logger.log: {format: "M num_high %.0f", args: [x]}
else:
- logger.log: {format: "M num_low %.0f", args: [x]}
switch:
- platform: template
id: sw
name: Sw
optimistic: true
on_turn_on:
- logger.log: "M sw_on"
- globals.set: {id: g_b, value: !lambda "return id(g_b) + 1;"}
- logger.log: {format: "M sw_on_b %d", args: [id(g_b)]}
on_turn_off:
- logger.log: "M sw_off"
select:
- platform: template
id: sel
name: Sel
optimistic: true
options: [a, b, c]
initial_option: a
on_value:
- logger.log: {format: "M sel_on_value %s idx %d", args: [x.c_str(), (int) i]}
sensor:
- platform: template
id: sens
name: Sens
update_interval: never
on_value_range:
- above: 50
then:
- logger.log: {format: "M sens_above %.0f", args: [x]}
- below: 10
then:
- logger.log: {format: "M sens_below %.0f", args: [x]}
alarm_control_panel:
- platform: template
id: acp
name: Acp
codes: ["1234"]
requires_code_to_arm: false
arming_away_time: 0s
on_armed_away:
- logger.log: "M acp_armed_away"
on_disarmed:
- logger.log: "M acp_disarmed"
on_state:
- logger.log: "M acp_state"
button:
- platform: template
name: Run All
on_press:
- logger.log: "M press_run_all"
- script.execute: master
- platform: template
name: Chain Button
on_press:
- logger.log: "M cb_1"
- lambda: id(g_a) = 7;
- globals.set: {id: g_b, value: "3"}
- logger.log: {format: "M cb_2 %d %d", args: [id(g_a), id(g_b)]}
- switch.toggle: sw
- logger.log: "M cb_3"
script:
- id: s_single
mode: single
parameters: {x: int}
then:
- logger.log: {format: "M single_start %d", args: [x]}
- delay: 150ms
- logger.log: {format: "M single_end %d", args: [x]}
- id: s_restart
mode: restart
parameters: {x: int, s: string}
then:
- logger.log: {format: "M restart_start %d %s", args: [x, s.c_str()]}
- delay: 150ms
- logger.log: {format: "M restart_end %d %s", args: [x, s.c_str()]}
- id: s_queued
mode: queued
max_runs: 5
parameters: {x: int}
then:
- logger.log: {format: "M queued_start %d", args: [x]}
- delay: 60ms
- logger.log: {format: "M queued_end %d", args: [x]}
- id: s_parallel
mode: parallel
parameters: {x: int}
then:
- logger.log: {format: "M parallel_start %d", args: [x]}
- delay: !lambda "return 50 + x * 30;"
- logger.log: {format: "M parallel_end %d", args: [x]}
- id: s_selfstop
mode: single
then:
- logger.log: "M selfstop_1"
- lambda: id(g_a) = 100;
- script.stop: s_selfstop
- logger.log: "M selfstop_SHOULD_NOT_RUN"
- lambda: id(g_a) = 200;
- id: s_par_self
mode: parallel
max_runs: 2
then:
- lambda: id(g_par)++;
- logger.log: {format: "M parself_run %d running=%d", args: [id(g_par), (int) id(s_par_self).is_running()]}
- if:
condition:
lambda: return id(g_par) < 4;
then:
- script.execute: s_par_self
- delay: 200ms
- id: s_par3
mode: parallel
max_runs: 3
then:
- lambda: id(g_par3)++;
- logger.log: {format: "M par3_run %d", args: [id(g_par3)]}
- if:
condition:
lambda: return id(g_par3) < 8;
then:
- script.execute: s_par3
- delay: 200ms
- id: s_par4
mode: parallel
max_runs: 4
then:
- lambda: id(g_par4)++;
- logger.log: {format: "M par4_run %d", args: [id(g_par4)]}
- if:
condition:
lambda: return id(g_par4) < 8;
then:
- script.execute: s_par4
- delay: 200ms
- id: master
mode: single
then:
- logger.log: "M c1_chain_start"
- lambda: id(g_a) = 1;
- globals.set: {id: g_b, value: "2"}
- logger.log: {format: "M c1_vals %d %d", args: [id(g_a), id(g_b)]}
- switch.turn_on: sw
- number.set: {id: num, value: 42}
- select.set: {id: sel, option: b}
- lambda: |-
int local = id(g_a) + id(g_b);
if (local > 0) { ESP_LOGI("main", "M c1_lambda_local %d", local); return; }
ESP_LOGI("main", "M c1_lambda_NOT_REACHED");
- logger.log: "M c1_after_return"
- logger.log: "M c2_delay_chain_start"
- delay: 50ms
- logger.log: "M c2_after_delay"
- lambda: id(g_a) = 5;
- delay: 0ms
- logger.log: {format: "M c2_end %d", args: [id(g_a)]}
- logger.log: "M c3_if_start"
- repeat:
count: 4
then:
- if:
condition:
and:
- lambda: return iteration % 2 == 0;
- not:
lambda: return iteration == 2;
then:
- logger.log: {format: "M c3_even_not2 %d", args: [iteration]}
else:
- if:
condition:
or:
- lambda: return iteration == 1;
- xor:
- lambda: return iteration == 2;
- lambda: return false;
then:
- logger.log: {format: "M c3_or_xor %d", args: [iteration]}
else:
- logger.log: {format: "M c3_else %d", args: [iteration]}
- logger.log: "M c4_choose_start"
- repeat:
count: 3
then:
- choose:
- if:
lambda: return iteration == 0;
then:
- logger.log: {format: "M c4_choice0 %d", args: [iteration]}
- if:
lambda: return iteration == 1;
then:
- logger.log: {format: "M c4_choice1 %d", args: [iteration]}
- else:
- logger.log: {format: "M c4_default %d", args: [iteration]}
- logger.log: "M c5_while_start"
- globals.set: {id: g_a, value: "0"}
- while:
condition:
lambda: return id(g_a) < 4;
then:
- logger.log: {format: "M c5_while %d", args: [id(g_a)]}
- lambda: id(g_a)++;
- logger.log: {format: "M c5_while_done %d", args: [id(g_a)]}
- globals.set: {id: g_a, value: "0"}
- while:
condition:
lambda: return id(g_a) < 3;
then:
- logger.log: {format: "M c5_while_delay %d", args: [id(g_a)]}
- delay: 20ms
- lambda: id(g_a)++;
- logger.log: {format: "M c5_while_delay_done %d", args: [id(g_a)]}
- logger.log: "M c6_repeat_start"
- repeat:
count: 2
then:
- lambda: id(g_b) = iteration;
- repeat:
count: 3
then:
- logger.log: {format: "M c6_nested outer=%d inner=%d", args: [id(g_b), iteration]}
- repeat:
count: !lambda "return id(g_b) + 2;"
then:
- logger.log: {format: "M c6_dyn %d", args: [iteration]}
- delay: 10ms
- logger.log: "M c7_wait_until_start"
- lambda: |-
id(g_tick) = 0;
id(g_ticking) = true;
- wait_until:
condition:
lambda: return id(g_tick) >= 3;
timeout: 2s
- logger.log: {format: "M c7_waited %d", args: [(int) (id(g_tick) >= 3)]}
- wait_until:
condition:
for:
time: 300ms
condition:
lambda: return id(g_tick) >= 3;
timeout: 3s
- lambda: id(g_ticking) = false;
- logger.log: "M c7_for_done"
- logger.log: "M c8_scripts_start"
- script.execute: {id: s_single, x: 1}
- script.execute: {id: s_single, x: 2}
- script.wait: s_single
- script.execute: {id: s_restart, x: 1, s: one}
- delay: 40ms
- script.execute: {id: s_restart, x: 2, s: two}
- script.wait: s_restart
- script.execute: {id: s_queued, x: 1}
- script.execute: {id: s_queued, x: 2}
- script.execute: {id: s_queued, x: 3}
- script.wait: s_queued
- script.execute: {id: s_parallel, x: 2}
- script.execute: {id: s_parallel, x: 1}
- script.wait: s_parallel
- logger.log: "M c9_selfstop_start"
- script.execute: s_selfstop
- script.wait: s_selfstop
- logger.log: {format: "M c9_selfstop_g_a %d", args: [id(g_a)]}
- logger.log: "M c10_sensor_start"
- sensor.template.publish: {id: sens, state: 60}
- sensor.template.publish: {id: sens, state: 30}
- sensor.template.publish: {id: sens, state: 5}
- logger.log: "M c11_acp_start"
- alarm_control_panel.arm_away: acp
- delay: 100ms
- alarm_control_panel.disarm: {id: acp, code: "1234"}
- delay: 100ms
- logger.log: "M c12_parself_start"
- globals.set: {id: g_par, value: "0"}
- script.execute: s_par_self
- delay: 800ms
- logger.log: {format: "M c12_parself_total %d", args: [id(g_par)]}
- logger.log: "M c13_parmax_start"
- globals.set: {id: g_par3, value: "0"}
- script.execute: s_par3
- delay: 800ms
- logger.log: {format: "M c13_par3_total %d", args: [id(g_par3)]}
- globals.set: {id: g_par4, value: "0"}
- script.execute: s_par4
- delay: 800ms
- logger.log: {format: "M c13_par4_total %d", args: [id(g_par4)]}
- switch.turn_off: sw
- logger.log: "M done"
esphome:
on_boot:
priority: -100
then:
- logger.log: "M boot"
- delay: 8s
- script.execute: master
.agents/skills/hardware-test/scripts/automation_trace/drive.py
+72
View File
@@ -0,0 +1,72 @@
"""Record every 'M ...' marker from the device log while driving the automation trace config.
usage: drive.py HOST OUT env: API_KEY (unset for a plaintext API)
Order: wait for the boot run's 'M done', press Run All and wait for 'M done' again, press Chain Button twice, set Num
70 then 20, toggle Sw on and off, select c then a. Writes one marker per line to OUT (timestamps dropped). Exits 1
when the Run All pass never reached 'M done'.
"""
import asyncio
import pathlib
import re
import sys
from aioesphomeapi import LogLevel
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from apiconn import connect, log_text # noqa: E402
HOST, OUT = sys.argv[1], sys.argv[2]
marks: list[str] = []
done = asyncio.Event()
async def main() -> bool:
cli = await connect(HOST)
def on_log(m) -> None:
if mm := re.search(r"\]: (M .*)$", log_text(m)):
marks.append(mm.group(1).strip())
if mm.group(1).strip() == "M done":
done.set()
cli.subscribe_logs(on_log, log_level=LogLevel.LOG_LEVEL_DEBUG)
infos, _ = await cli.list_entities_services()
by = {i.name: i for i in infos}
try:
await asyncio.wait_for(done.wait(), 40)
except TimeoutError:
marks.append("DRIVER boot run not seen")
marks.append("DRIVER press Run All")
done.clear()
cli.button_command(by["Run All"].key)
ok = True
try:
await asyncio.wait_for(done.wait(), 40)
except TimeoutError:
marks.append("DRIVER run all timed out")
ok = False
steps = (
("cb1", lambda: cli.button_command(by["Chain Button"].key)),
("cb2", lambda: cli.button_command(by["Chain Button"].key)),
("num70", lambda: cli.number_command(by["Num"].key, 70.0)),
("num20", lambda: cli.number_command(by["Num"].key, 20.0)),
("swon", lambda: cli.switch_command(by["Sw"].key, True)),
("swoff", lambda: cli.switch_command(by["Sw"].key, False)),
("selc", lambda: cli.select_command(by["Sel"].key, "c")),
("sela", lambda: cli.select_command(by["Sel"].key, "a")),
)
for label, send in steps:
marks.append(f"DRIVER {label}")
send()
await asyncio.sleep(0.8)
await asyncio.sleep(1)
await cli.disconnect()
return ok
OK = asyncio.run(main())
pathlib.Path(OUT).write_text("\n".join(marks) + "\n", encoding="utf-8")
print(f"{len(marks)} lines")
sys.exit(0 if OK else 1)
.agents/skills/hardware-test/scripts/automation_trace/run.sh
Executable
+40
View File
@@ -0,0 +1,40 @@
#!/bin/bash
# run.sh LABEL: build the automation trace config as at<LABEL> from TREE, flash it over PORT, read the device address
# from the serial log, record the marker trace with drive.py and keep the part from "DRIVER press Run All" on in
# out-at<LABEL>.trace. Diff the .trace files of dev and the PR; the boot run is partly missed while the API connects.
# Run it from a scratch copy of this directory with a secrets.yaml (wifi_ssid, wifi_password).
# env: TREE (esphome checkout), PORT (serial port), SC (path to serial_capture.py), PY (checkout python),
# BOARD (esp32 board, default esp32dev), VARIANT (default esp32), API_KEY (only if you add api encryption)
R=$(cd "$(dirname "$0")" && pwd); L=${1:?label}; T=${TREE:?set TREE}; P=${PORT:?set PORT}
PY=${PY:-$T/venv/bin/python}; SC=${SC:?set SC}; NAME=at$L; OUT=$R/out-$NAME; rm -rf "$OUT"; mkdir -p "$OUT"
cat > "$R/$NAME.yaml" <<YAML
esphome:
name: $NAME
esp32:
board: ${BOARD:-esp32dev}
variant: ${VARIANT:-esp32}
framework:
type: esp-idf
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
packages:
trace: !include automation-trace-common.yaml
YAML
pkill -f "[s]erial_capture.py $P"
(cd "$T" && $PY -m esphome run --no-logs "$R/$NAME.yaml" --device "$P" > "$OUT/upload.log" 2>&1) || { echo "build or upload failed"; exit 1; }
grep -a -E '^(RAM|Flash):' "$OUT/upload.log"
$PY "$SC" "$P" 120 "$OUT/serial.txt" --reset > /dev/null 2>&1 &
CAP=$!; trap 'kill $CAP 2>/dev/null' EXIT
H=; for _ in $(seq 60); do
H=$(grep -a -o -E 'IP Address: [0-9.]+' "$OUT/serial.txt" 2>/dev/null | tail -1 | awk '{print $3}'); [ -n "$H" ] && break; sleep 1
done
[ -n "$H" ] || { echo "FAIL: no IP address in the serial log"; exit 1; }
PYTHONPATH=$(dirname "$SC") $PY "$R/drive.py" "$H" "$OUT/markers.txt"; RC=$?
sed -n '/^DRIVER press Run All/,$p' "$OUT/markers.txt" > "$R/out-$NAME.trace"
CR=$(grep -a -c -E 'Guru|abort\(\)|Backtrace|task_wdt' "$OUT/serial.txt")
echo "$NAME: $(wc -l < "$R/out-$NAME.trace") trace lines, crashes $CR"
[ "$CR" = 0 ] || { echo "FAIL: a crash or watchdog in the serial log"; exit 1; }
[ "$RC" = 0 ] || { echo "FAIL: Run All never reached M done"; exit 1; }
grep -q -E "SHOULD_NOT_RUN|NOT_REACHED" "$R/out-$NAME.trace" && { echo "FAIL: a step that must be skipped ran"; exit 1; }
echo PASS
.agents/skills/hardware-test/scripts/bk72xx_flash/partdiff.py
+64
View File
@@ -0,0 +1,64 @@
"""Compare two full flash dumps of a BK72xx board per partition of its LibreTiny board layout.
usage: partdiff.py BEFORE.bin AFTER.bin LAYOUT.json
LAYOUT.json is a board base file from the LibreTiny platform (for example boards/_base/beken-72xx.json); its
"flash" map ("name": "0xSTART+0xLENGTH") names the partitions. Prints the 4 KB sectors that changed in each one,
plus any changed sector outside the map (a WARN, to check by hand). Exits 1 when the bootloader, calibration or
userdata partition changed.
"""
import json
import pathlib
import sys
before, after = (pathlib.Path(p).read_bytes() for p in sys.argv[1:3])
if len(before) != len(after):
sys.exit(
f"dump sizes differ: {len(before)} and {len(after)} bytes; compare two whole chip reads"
)
parts = []
for name, span in json.loads(pathlib.Path(sys.argv[3]).read_text(encoding="utf-8"))[
"flash"
].items():
start, length = (int(x, 16) for x in span.split("+"))
parts.append((start, start + length, name))
parts.sort()
PROTECTED = ("bootloader", "calibration", "userdata")
if missing := [n for n in PROTECTED if n not in {name for _, _, name in parts}]:
sys.exit(
f"the layout has no {', '.join(missing)} partition; use the Beken board base file"
)
if (end := max(e for _, e, _ in parts)) > len(before):
sys.exit(
f"the layout reaches {end:#x} but the dumps are {len(before):#x} bytes; read the whole chip"
)
SECTOR = 0x1000
covered = set()
protected = []
for start, end, name in parts:
changed = [
a
for a in range(start, end, SECTOR)
if before[a : a + SECTOR] != after[a : a + SECTOR]
]
covered.update(range(start, end, SECTOR))
if changed and name in PROTECTED:
protected.append(name)
listed = " ".join(hex(a) for a in changed[:4]) if 0 < len(changed) <= 4 else ""
print(
f"{name:12} {len(changed):4} of {(end - start) // SECTOR:4} sectors changed {listed}"
)
other = [
a
for a in range(0, len(before), SECTOR)
if a not in covered and before[a : a + SECTOR] != after[a : a + SECTOR]
]
print(
f"{'unmapped':12} {len(other):4} sectors changed {' '.join(hex(a) for a in other[:8])}"
)
if other:
print(
"WARN: sectors outside the layout changed; check what they held in the backup"
)
if protected:
sys.exit(f"FAIL: {', '.join(protected)} changed")
.agents/skills/hardware-test/scripts/bk72xx_flash/readback.sh
Executable
+19
View File
@@ -0,0 +1,19 @@
#!/bin/bash
# usage: readback.sh TAG [START LENGTH] read flash from a BK72xx over its adapter into TAG.bin (whole chip by default)
# env: PORT (adapter), FAMILY (ltchiptool family, default beken-7238), FLASH_BK (path to flash_bk72xx.py),
# LT (LibreTiny penv python, default ~/.platformio/penv/.libretiny/bin/python), SIZE (whole chip bytes, default
# 2097152). A whole 2 MB chip takes about 190 s. The read must come back at the expected size.
T=${1:?tag}; P=${PORT:?set PORT}; FB=${FLASH_BK:?set FLASH_BK}; LT=${LT:-$HOME/.platformio/penv/.libretiny/bin/python}
ARGS=(); [ -n "$2" ] && ARGS=(-s "$2" -l "${3:?length}")
WANT=$(( ${3:-${SIZE:-2097152}} ))
: > "$T.log"
ok=
for i in 1 2 3; do
echo "### try $i" >> "$T.log"
rm -f "$T.bin"
timeout 900 "$LT" "$FB" flash read -d "$P" "${ARGS[@]}" "${FAMILY:-beken-7238}" "$T.bin" >> "$T.log" 2>&1 &&
[ "$(wc -c < "$T.bin" | tr -d ' ')" = "$WANT" ] && ok=1 && break
sleep 3
done
[ -n "$ok" ] || { echo "FAIL: read $T (expected $WANT bytes, see $T.log)"; exit 1; }
shasum -a 256 "$T.bin"
.agents/skills/hardware-test/scripts/ble_adv_triggers/adv_frames.hpp
+61
View File
@@ -0,0 +1,61 @@
#pragma once
// Rotating non-connectable advertisements with known service and manufacturer data (random static addresses).
#include <esp_gap_ble_api.h>
#include <cstring>
#include "esphome/core/log.h"
namespace af {
struct Frame {
uint8_t last; // address C4:C1:38:00:00:<last>
uint8_t len;
uint8_t adv[31];
};
// AD structures after the flags. 0x16 = service data 16-bit, 0x20 = 32-bit, 0x21 = 128-bit, 0xFF = manufacturer.
static const Frame FRAMES[] = {
// 21: service 181C AA01 + manufacturer 02E5 BB01
{0x21, 12, {5, 0x16, 0x1C, 0x18, 0xAA, 0x01, 5, 0xFF, 0xE5, 0x02, 0xBB, 0x01}},
// 22: service 32-bit 12345678 AA02
{0x22, 8, {7, 0x20, 0x78, 0x56, 0x34, 0x12, 0xAA, 0x02}},
// 23: service 128-bit 12345678-9ABC-DEF0-1122-334455667788 (wire order) AA03
{0x23, 20, {19, 0x21, 0x88, 0x77, 0x66, 0x55, 0x44, 0x33, 0x22, 0x11,
0xF0, 0xDE, 0xBC, 0x9A, 0x78, 0x56, 0x34, 0x12, 0xAA, 0x03}},
// 24: manufacturer 181C BB04 (same id as the service UUID of 21, other data kind)
{0x24, 6, {5, 0xFF, 0x1C, 0x18, 0xBB, 0x04}},
// 25: service 181C AA05 then a second 181C entry AA06 (only the first may fire)
{0x25, 12, {5, 0x16, 0x1C, 0x18, 0xAA, 0x05, 5, 0x16, 0x1C, 0x18, 0xAA, 0x06}},
// 26: the 128-bit UUID in printed byte order AA07 (must not match)
{0x26, 20, {19, 0x21, 0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC, 0xDE, 0xF0,
0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0xAA, 0x07}},
};
static constexpr int COUNT = sizeof(FRAMES) / sizeof(FRAMES[0]);
static uint32_t failed = 0;
static uint32_t sent = 0;
inline void send(int i) {
const Frame &f = FRAMES[i];
uint8_t adv[31];
uint8_t n = 0;
adv[n++] = 2;
adv[n++] = 0x01;
adv[n++] = 0x06;
memcpy(adv + n, f.adv, f.len);
n += f.len;
esp_ble_gap_stop_advertising();
uint8_t addr[6] = {0xC4, 0xC1, 0x38, 0x00, 0x00, f.last};
esp_err_t e1 = esp_ble_gap_set_rand_addr(addr);
esp_err_t e2 = esp_ble_gap_config_adv_data_raw(adv, n);
esp_ble_adv_params_t p{};
p.adv_int_min = 0x20; // 20 ms
p.adv_int_max = 0x20;
p.adv_type = ADV_TYPE_NONCONN_IND;
p.own_addr_type = BLE_ADDR_TYPE_RANDOM;
p.channel_map = ADV_CHNL_ALL;
p.adv_filter_policy = ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY;
esp_err_t e3 = esp_ble_gap_start_advertising(&p);
sent++;
if (e1 != ESP_OK || e2 != ESP_OK || e3 != ESP_OK) {
failed++;
ESP_LOGW("af", "frame %d failed: %d %d %d", i, e1, e2, e3);
}
}
} // namespace af
.agents/skills/hardware-test/scripts/ble_adv_triggers/advtrig.yaml
+41
View File
@@ -0,0 +1,41 @@
# Advertiser for the service and manufacturer data trigger test: any ESP32 with BLE. Every 250 ms it switches to
# the next of six raw non-connectable advertisements in adv_frames.hpp (addresses C4:C1:38:00:00:21 to 26).
esphome:
name: advtrig
includes:
- adv_frames.hpp
esp32:
board: esp32-s3-devkitc-1
variant: esp32s3
framework:
type: esp-idf
logger:
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
api:
reboot_timeout: 0s
ota:
- platform: esphome
esp32_ble:
globals:
- id: idx
type: int
initial_value: "0"
interval:
- interval: 250ms
then:
- lambda: |-
af::send(id(idx));
id(idx) = (id(idx) + 1) % af::COUNT;
- interval: 30s
then:
- lambda: ESP_LOGI("af", "sent %u, failed %u", (unsigned) af::sent, (unsigned) af::failed);
.agents/skills/hardware-test/scripts/ble_adv_triggers/check.py
+72
View File
@@ -0,0 +1,72 @@
"""check.py CAPTURE [--zero-mac any|filter]: judge the last count report of a receiver capture.
Expected per trigger (see triggers.yaml): T1 AA01+AA05, T2 AA01, T3 nothing, T4 AA02, T5 AA03, T6 BB01, T7 BB04,
T8 the same count as T2, T9 (mac 00:00:00:00:00:00) AA01+AA05 with --zero-mac any or nothing with filter,
T10 AA03, T11 nothing. "other" on a trigger without a MAC filter is another device in range and is only reported.
Prints PASS or FAIL with the reason and exits 0 or 1.
"""
import argparse
import pathlib
import re
import sys
NO_MAC = {1, 7, 10}
def main() -> int:
parser = argparse.ArgumentParser(
description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
)
parser.add_argument("capture")
parser.add_argument("--zero-mac", choices=["any", "filter"], default="filter")
args = parser.parse_args()
zero = args.zero_mac
text = pathlib.Path(args.capture).read_text(encoding="utf-8", errors="replace")
rows: dict[int, dict[str, int]] = {}
for m in re.finditer(r"count T(\d+):([^\n]*)", text):
counts = dict(re.findall(r"(AA\d\d|BB\d\d|other)=(\d+)", m.group(2)))
rows[int(m.group(1))] = {k: int(v) for k, v in counts.items()}
if len(rows) != 11:
print(
f"FAIL: found {len(rows)} trigger rows, want 11 (no report in the capture?)"
)
return 1
want = {
1: {"AA01", "AA05"},
2: {"AA01"},
3: set(),
4: {"AA02"},
5: {"AA03"},
6: {"BB01"},
7: {"BB04"},
8: {"AA01"},
9: {"AA01", "AA05"} if zero == "any" else set(),
10: {"AA03"},
11: set(),
}
# With --zero-mac any, the all-zero MAC means no filter, so T9 also hears other devices
no_mac = NO_MAC | {9} if zero == "any" else NO_MAC
bad = []
for t, keys in want.items():
got = {k for k in rows[t] if k != "other"}
if got != keys:
bad.append(f"T{t} fired on {sorted(got)}, want {sorted(keys)}")
if rows[t].get("other") and t not in no_mac:
bad.append(
f"T{t} has other={rows[t]['other']} although it filters on a MAC"
)
if keys and min(rows[t].get(k, 0) for k in keys) < 10:
bad.append(
f"T{t} has fewer than 10 hits on one of {sorted(keys)}: {rows[t]}"
)
if rows[8] != rows[2]:
bad.append(f"T8 {rows[8]} differs from T2 {rows[2]} (same filter)")
for t in sorted(rows):
print(f"T{t}: {rows[t]}")
print("FAIL: " + "; ".join(bad) if bad else "PASS")
return 1 if bad else 0
if __name__ == "__main__":
sys.exit(main())
.agents/skills/hardware-test/scripts/ble_adv_triggers/run.sh
Executable
+21
View File
@@ -0,0 +1,21 @@
#!/bin/bash
# run.sh esp32|bk72xx LABEL: build rx-<kind>.yaml as rx<kind><LABEL> from TREE, flash it, capture 150 s, run check.py.
# The advertiser (advtrig.yaml) must already be running on a second ESP32 in range.
# env: TREE (esphome checkout to build from), PORT (receiver serial port), SC (path to serial_capture.py),
# PY (checkout python), BOARD (bk72xx board, default xh-wb3s), BKPY + BKFLASH (python and flash_bk72xx.py for
# bk72xx), ZERO_MAC (any or filter, what mac_address 00:00:00:00:00:00 should do on this build; default filter)
R=$(cd "$(dirname "$0")" && pwd); K=${1:?esp32 or bk72xx}; L=${2:?label}; T=${TREE:?set TREE}; P=${PORT:?set PORT}
PY=${PY:-$T/venv/bin/python}; SC=${SC:?set SC}; NAME=rx$K$L; OUT=$R/out-$NAME; rm -rf "$OUT"; mkdir -p "$OUT"
sed -e "s/\${name}/$NAME/" -e "s/\${board}/${BOARD:-xh-wb3s}/" "$R/rx-$K.yaml" > "$R/$NAME.yaml"
pkill -f "[s]erial_capture.py $P"
if [ "$K" = esp32 ]; then
(cd "$T" && $PY -m esphome run --no-logs "$R/$NAME.yaml" --device "$P" > "$OUT/upload.log" 2>&1) || { echo "build or upload failed"; exit 1; }
$PY "$SC" "$P" 150 "$OUT/serial.txt" --reset > /dev/null 2>&1
else
(cd "$T" && $PY -m esphome compile "$R/$NAME.yaml" > "$OUT/compile.log" 2>&1) || { echo "build failed"; exit 1; }
${BKPY:?set BKPY} "${BKFLASH:?set BKFLASH}" flash write -d "$P" "$R/.esphome/build/$NAME/.pioenvs/$NAME/firmware.uf2" > "$OUT/flash.log" 2>&1 || { echo "flash failed"; exit 1; }
$PY "$SC" "$P" 150 "$OUT/serial.txt" > /dev/null 2>&1
fi
[ -s "$OUT/serial.txt" ] || { echo "serial capture got nothing"; exit 1; }
grep -a "adverts" "$OUT/serial.txt" | tail -1
$PY "$R/check.py" "$OUT/serial.txt" --zero-mac "${ZERO_MAC:-filter}"
.agents/skills/hardware-test/scripts/ble_adv_triggers/rx-bk72xx.yaml
+39
View File
@@ -0,0 +1,39 @@
# Receiver on a BK72xx board (bk72xx_ble_tracker). substitutions: name, board
# Wi-Fi must be configured: without it the BK7238 tracker logs "Scan started" and never receives anything.
esphome:
name: ${name}
includes:
- rx.hpp
bk72xx:
board: ${board}
logger:
hardware_uart: UART1
level: DEBUG
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
bk72xx_ble:
enable_on_boot: true
bk72xx_ble_tracker:
scan_parameters:
interval: 100ms
window: 30ms
continuous: true
<<: !include triggers.yaml
on_ble_advertise:
- then:
- lambda: |-
rx::all++;
if ((x.address_uint64() >> 8) == 0xC4C1380000ULL) rx::ours++;
interval:
- interval: 20s
then:
- lambda: |-
rx::report("count");
ESP_LOGI("rx", "adverts %u, from the advertiser %u", (unsigned) rx::all, (unsigned) rx::ours);
.agents/skills/hardware-test/scripts/ble_adv_triggers/rx-esp32.yaml
+32
View File
@@ -0,0 +1,32 @@
# Receiver on a classic ESP32 (esp32_ble_tracker). substitutions: name
esphome:
name: ${name}
includes:
- rx.hpp
esp32:
board: esp32dev
framework:
type: esp-idf
logger:
level: DEBUG
esp32_ble_tracker:
scan_parameters:
interval: 100ms
window: 100ms
active: false
<<: !include triggers.yaml
on_ble_advertise:
- then:
- lambda: |-
rx::all++;
if ((x.address_uint64() >> 8) == 0xC4C1380000ULL) rx::ours++;
interval:
- interval: 20s
then:
- lambda: |-
rx::report("count");
ESP_LOGI("rx", "adverts %u, from the advertiser %u", (unsigned) rx::all, (unsigned) rx::ours);
.agents/skills/hardware-test/scripts/ble_adv_triggers/rx.hpp
+37
View File
@@ -0,0 +1,37 @@
#pragma once
// Per trigger counts of the received payloads: AAnn (service data) and BBnn (manufacturer data) from the advertiser,
// anything else counted as "other".
#include <cstdint>
#include <cstdio>
#include <vector>
#include "esphome/core/log.h"
namespace rx {
static constexpr int TRIGGERS = 12;
static uint32_t cnt[TRIGGERS][16];
static uint32_t other[TRIGGERS];
static uint32_t all, ours;
inline void hit(int t, const std::vector<uint8_t> &x) {
if (x.size() == 2 && (x[0] == 0xAA || x[0] == 0xBB) && x[1] >= 1 && x[1] <= 7) {
cnt[t][(x[0] == 0xBB ? 8 : 0) + x[1]]++;
} else {
other[t]++;
}
}
inline void report(const char *label) {
for (int t = 1; t < TRIGGERS; t++) {
char buf[160];
int n = snprintf(buf, sizeof(buf), "T%d:", t);
for (int k = 0; k < 16; k++) {
if (cnt[t][k])
n += snprintf(buf + n, sizeof(buf) - n, " %s%02u=%u", k >= 8 ? "BB" : "AA", (unsigned) (k & 7),
(unsigned) cnt[t][k]);
}
if (other[t])
n += snprintf(buf + n, sizeof(buf) - n, " other=%u", (unsigned) other[t]);
ESP_LOGI("rx", "%s %s", label, buf);
}
}
} // namespace rx
.agents/skills/hardware-test/scripts/ble_adv_triggers/triggers.yaml
+44
View File
@@ -0,0 +1,44 @@
# Shared trigger block, included under the tracker key.
on_ble_service_data_advertise:
- service_uuid: 181C
then:
- lambda: rx::hit(1, x);
- mac_address: C4:C1:38:00:00:21
service_uuid: 181C
then:
- lambda: rx::hit(2, x);
- mac_address: C4:C1:38:00:00:22
service_uuid: 181C
then:
- lambda: rx::hit(3, x);
- mac_address: C4:C1:38:00:00:22
service_uuid: "12345678"
then:
- lambda: rx::hit(4, x);
- mac_address: C4:C1:38:00:00:23
service_uuid: 12345678-9ABC-DEF0-1122-334455667788
then:
- lambda: rx::hit(5, x);
- mac_address: C4:C1:38:00:00:21
service_uuid: 181C
then:
- lambda: rx::hit(8, x);
- mac_address: 00:00:00:00:00:00
service_uuid: 181C
then:
- lambda: rx::hit(9, x);
- service_uuid: 12345678-9ABC-DEF0-1122-334455667788
then:
- lambda: rx::hit(10, x);
on_ble_manufacturer_data_advertise:
- mac_address: C4:C1:38:00:00:21
manufacturer_id: 02E5
then:
- lambda: rx::hit(6, x);
- manufacturer_id: 181C
then:
- lambda: rx::hit(7, x);
- mac_address: C4:C1:38:00:00:22
manufacturer_id: 02E5
then:
- lambda: rx::hit(11, x);
.agents/skills/hardware-test/scripts/ble_event_inject/cp-inject.yaml
+39
View File
@@ -0,0 +1,39 @@
# Add to a copy of a bluetooth_proxy config: packages: {cp_inject: !include cp-inject.yaml}
esphome:
includes:
- cp_inject.hpp
logger:
level: VERBOSE
logs:
esp32_ble_tracker: DEBUG
bluetooth_proxy: DEBUG
bluetooth_connection: DEBUG
api: DEBUG
api.service: DEBUG
api.connection: DEBUG
api.socket: DEBUG
scheduler: DEBUG
sensor: DEBUG
component: DEBUG
button:
- platform: template
name: Inject conn param events
# The handlers push into a queue that takes one writer only, the Bluetooth task. Stop the scan (and keep the
# proxy free of real connections) so nothing else writes while the button does.
on_press:
- esp32_ble_tracker.stop_scan:
- wait_until:
condition:
lambda: return !esp32_ble_tracker::global_esp32_ble_tracker->scan_running();
timeout: 5s
- delay: 1s
- lambda: |-
if (esp32_ble_tracker::global_esp32_ble_tracker->scan_running()) {
ESP_LOGE("cpinject", "scan still running after 5 s, nothing injected");
return;
}
cpinject::run();
- esp32_ble_tracker.start_scan:
continuous: true
.agents/skills/hardware-test/scripts/ble_event_inject/cp_inject.hpp
+68
View File
@@ -0,0 +1,68 @@
#pragma once
// Feeds fabricated conn param update and disconnect events into ESP32BLE's static handlers.
// The event queue takes a single writer: call run() only while scanning is stopped and no connection is active.
#include <cstring>
#include "esphome/components/esp32_ble/ble.h"
#include "esphome/core/log.h"
namespace cpinject {
using GapFn = void (*)(esp_gap_ble_cb_event_t, esp_ble_gap_cb_param_t *);
using GattcFn = void (*)(esp_gattc_cb_event_t, esp_gatt_if_t, esp_ble_gattc_cb_param_t *);
GapFn steal_gap();
GattcFn steal_gattc();
// Explicit instantiation ignores access checks, which exposes the protected static handlers.
template<GapFn F> struct GapThief {
friend GapFn steal_gap() { return F; }
};
template<GattcFn F> struct GattcThief {
friend GattcFn steal_gattc() { return F; }
};
template struct GapThief<&esphome::esp32_ble::ESP32BLE::gap_event_handler>;
template struct GattcThief<&esphome::esp32_ble::ESP32BLE::gattc_event_handler>;
static const char *const TAG = "cpinject";
inline void peer(uint8_t n, uint8_t *bda) {
const uint8_t base[6] = {0xC0, 0xFF, 0xEE, 0x00, 0x00, 0x00};
memcpy(bda, base, 6);
bda[5] = n;
}
inline void update(uint8_t n, int status, int times) {
for (int i = 0; i < times; i++) {
esp_ble_gap_cb_param_t p{};
peer(n, p.update_conn_params.bda);
p.update_conn_params.status = (esp_bt_status_t) status;
p.update_conn_params.conn_int = 24;
p.update_conn_params.timeout = 400;
steal_gap()(ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT, &p);
}
}
inline void disconnect(uint8_t n) {
esp_ble_gattc_cb_param_t p{};
peer(n, p.disconnect.remote_bda);
p.disconnect.reason = ESP_GATT_CONN_TERMINATE_PEER_USER;
p.disconnect.conn_id = 0xEE;
// 0xFE matches no registered client, so the queued event is ignored by every connection.
steal_gattc()(ESP_GATTC_DISCONNECT_EVT, 0xFE, &p);
}
inline void run() {
ESP_LOGI(TAG, "STEP1 peers 1-4 fail 5x each (3 slots)");
for (uint8_t n = 1; n <= 4; n++)
update(n, 6, 5);
ESP_LOGI(TAG, "STEP2 peer 1 succeeds, then fails 3x");
update(1, 0, 1);
update(1, 6, 3);
ESP_LOGI(TAG, "STEP3 peer 2 disconnects, then fails 3x");
disconnect(2);
update(2, 6, 3);
ESP_LOGI(TAG, "STEP4 peer 4 fails 3x, slots still full");
update(4, 6, 3);
ESP_LOGI(TAG, "STEP5 peer 3 disconnects, peer 4 fails 3x");
disconnect(3);
update(4, 6, 3);
ESP_LOGI(TAG, "STEP6 done");
}
} // namespace cpinject
.agents/skills/hardware-test/scripts/ble_event_inject/tpinject.hpp
+63
View File
@@ -0,0 +1,63 @@
#pragma once
// Injects ThermoPro advertisements (the records from the thermopro_ble unit tests, #22047) as scan results.
// Call inject_all() from the main loop; MACs are A4:C1:38:00:10:01 to :10, one per frame.
#include <cstring>
#include "esphome/components/esp32_ble_tracker/esp32_ble_tracker.h"
namespace tpinject {
struct Frame {
uint8_t mac_last;
const char *name;
uint8_t len;
uint8_t rec[25];
};
static constexpr Frame FRAMES[] = {
{0x01, "TP357 (2142)", 6, {0xC2, 0xF1, 0x00, 0x1D, 0x02, 0x2C}},
{0x02, "TP357S (2142)", 7, {0xC2, 0xEE, 0x00, 0x29, 0x22, 0x0B, 0x01}},
{0x03, "TP393 (9376)", 6, {0xC2, 0xF2, 0x00, 0x35, 0x02, 0x2C}},
{0x04, "TP960R", 7, {0x00, 0x3A, 0x00, 0x30, 0x08, 0x38, 0x00}},
{0x05, "TP970R", 7, {0x00, 0x35, 0x00, 0x46, 0x0B, 0x35, 0x00}},
{0x06, "TP972S", 23, {0x00, 0x72, 0x00, 0x6A, 0x0A, 0x33, 0xD3, 0xB8, 0x42, 0x00, 0x40, 0xAE,
0x42, 0x66, 0x06, 0xAE, 0x42, 0x6C, 0x54, 0x73, 0x77, 0x44, 0xF8}},
{0x07, "TP972S", 23, {0x00, 0x8D, 0x00, 0xA6, 0x0A, 0xCD, 0xEC, 0xFF, 0x42, 0x9A, 0x69, 0x00,
0x43, 0x9A, 0x69, 0x00, 0x43, 0x6C, 0x54, 0x73, 0x77, 0x44, 0xF8}},
{0x08, "TP972S", 13, {0x00, 0x33, 0x00, 0x48, 0x0A, 0x33, 0x00, 0xFF, 0xEE, 0xDD, 0xCC, 0xBB, 0xAA}},
{0x09, "TP960R", 13, {0x00, 0x3A, 0x00, 0x30, 0x08, 0x38, 0x00, 0xFF, 0xEE, 0xDD, 0xCC, 0xBB, 0xAA}},
{0x0A, "TP970R", 23, {0x00, 0x72, 0x00, 0x6A, 0x0A, 0x33, 0xD3, 0xB8, 0x42, 0x00, 0x40, 0xAE,
0x42, 0x66, 0x06, 0xAE, 0x42, 0x6C, 0x54, 0x73, 0x77, 0x44, 0xF8}},
{0x0B, "TP357S (3C62)", 7, {0xC2, 0xFF, 0xFF, 0xFF, 0x22, 0x0B, 0x01}},
{0x0C, "TP357 (2142)", 6, {0xC2, 0xF1, 0x00, 0x1D, 0x00, 0x2C}},
{0x0D, "TP357 (2142)", 6, {0xC2, 0xF1, 0x00, 0x1D, 0x03, 0x2C}},
{0x0E, "TP357 (2142)", 6, {0xC2, 0xCE, 0xFF, 0x1D, 0x02, 0x2C}},
{0x0F, "TP972S", 25, {0xC2, 0xC7, 0x01, 0x8D, 0x00, 0xE1, 0x0A, 0x33, 0x13, 0xFA, 0x42, 0x00, 0xC0,
0xFA, 0x42, 0x9A, 0xF9, 0xFA, 0x42, 0x6C, 0x54, 0x73, 0x77, 0x44, 0xF8}},
{0x10, "TP25", 6, {0xC2, 0xF1, 0x00, 0x1D, 0x02, 0x2C}},
};
inline void inject_all() {
for (const auto &f : FRAMES) {
esphome::esp32_ble::BLEScanResult r{};
const uint8_t mac[6] = {0xA4, 0xC1, 0x38, 0x00, 0x10, f.mac_last};
memcpy(r.bda, mac, 6);
r.ble_addr_type = 0;
r.rssi = -60 - f.mac_last;
uint8_t n = 0;
size_t nl = strlen(f.name);
r.ble_adv[n++] = 2;
r.ble_adv[n++] = 0x01;
r.ble_adv[n++] = 0x06;
r.ble_adv[n++] = nl + 1;
r.ble_adv[n++] = 0x09;
memcpy(r.ble_adv + n, f.name, nl);
n += nl;
r.ble_adv[n++] = f.len + 1;
r.ble_adv[n++] = 0xFF;
memcpy(r.ble_adv + n, f.rec, f.len);
n += f.len;
r.adv_data_len = n;
r.scan_rsp_len = 0;
r.search_evt = ESP_GAP_SEARCH_INQ_RES_EVT;
esphome::esp32_ble_tracker::global_esp32_ble_tracker->gap_scan_event_handler(r);
}
}
} // namespace tpinject
.agents/skills/hardware-test/scripts/ble_notify/client.yaml
+72
View File
@@ -0,0 +1,72 @@
# ble_client (classic ESP32): a sensor and a text sensor with notify, two on_notify each, link cycle every 60 s.
# Substitutions: name, server (the server's BLE MAC from its esp32_ble dump).
esphome:
name: ${name}
esp32:
board: esp32dev
framework:
type: esp-idf
logger:
level: DEBUG
esp32_ble_tracker:
scan_parameters:
active: false
ble_client:
- mac_address: ${server}
id: srv
on_connect:
- logger.log: {format: "CLI connected", level: INFO}
on_disconnect:
- logger.log: {format: "CLI disconnected", level: INFO}
sensor:
- platform: ble_client
type: characteristic
ble_client_id: srv
id: num
name: num
service_uuid: 5ec10000-0000-1000-8000-00805f9b34fb
characteristic_uuid: 5ec10001-0000-1000-8000-00805f9b34fb
notify: true
update_interval: never
lambda: |-
if (x.empty()) return -1.0f;
if (x.size() == 1) return x[0] * 10.0f;
return (float) ((x[1] << 8) | x[2]) * 10.0f;
on_value:
- logger.log: {format: "CLI num value %.1f", args: [x], level: INFO}
on_notify:
- then:
- logger.log: {format: "CLI num notify A %.1f", args: [x], level: INFO}
- then:
- logger.log: {format: "CLI num notify B %.1f", args: [x], level: INFO}
text_sensor:
- platform: ble_client
ble_client_id: srv
id: txt
name: txt
service_uuid: 5ec10000-0000-1000-8000-00805f9b34fb
characteristic_uuid: 5ec10002-0000-1000-8000-00805f9b34fb
notify: true
update_interval: never
on_value:
- logger.log: {format: "CLI txt value '%s'", args: [x.c_str()], level: INFO}
on_notify:
- then:
- logger.log: {format: "CLI txt notify A '%s' len=%u", args: [x.c_str(), (unsigned) x.size()], level: INFO}
- then:
- delay: 1s
- logger.log: {format: "CLI txt notify B '%s' len=%u", args: [x.c_str(), (unsigned) x.size()], level: INFO}
interval:
- interval: 60s
then:
- logger.log: {format: "CLI cycle link", level: INFO}
- ble_client.disconnect: srv
- delay: 3s
- ble_client.connect: srv
.agents/skills/hardware-test/scripts/ble_notify/run.sh
Executable
+29
View File
@@ -0,0 +1,29 @@
#!/bin/bash
# run.sh LABEL: build and flash the notify server (SERVER_PORT) and the ble_client (CLIENT_PORT) from TREE, capture
# the client 150 s (two link cycles) and count on_notify against on_value per sensor. Fails on a crash, no notify, the
# two triggers of a sensor firing a different number of times (the delayed txt one may miss the last notify), or no
# `services released` line (#21821).
# env: TREE (esphome checkout), SERVER_PORT, CLIENT_PORT, SERVER_BLE_MAC (from the server's esp32_ble dump; flash the
# server once and read it), SC (path to serial_capture.py), PY (checkout python)
R=$(cd "$(dirname "$0")" && pwd); L=${1:?label}; T=${TREE:?set TREE}; PY=${PY:-$T/venv/bin/python}; SC=${SC:?set SC}
SP=${SERVER_PORT:?set SERVER_PORT}; CP=${CLIENT_PORT:?set CLIENT_PORT}; MAC=${SERVER_BLE_MAC:?set SERVER_BLE_MAC}
OUT=$R/out-bn$L; rm -rf "$OUT"; mkdir -p "$OUT"
pkill -f "[s]erial_capture.py $SP"; pkill -f "[s]erial_capture.py $CP"
(cd "$T" && $PY -m esphome -s name "bnsrv$L" run --no-logs "$R/server.yaml" --device "$SP" > "$OUT/server-upload.log" 2>&1) ||
{ echo "FAIL: server build or upload"; exit 1; }
(cd "$T" && $PY -m esphome -s name "bncli$L" -s server "$MAC" run --no-logs "$R/client.yaml" --device "$CP" \
> "$OUT/client-upload.log" 2>&1) || { echo "FAIL: client build or upload"; exit 1; }
$PY "$SC" "$CP" 150 "$OUT/client.txt" --reset > /dev/null 2>&1 || { echo "FAIL: client capture got nothing"; exit 1; }
c() { grep -a -c "$1" "$OUT/client.txt"; }
echo "bn$L: connects $(c 'CLI connected'), num value $(c 'CLI num value') notify A $(c 'num notify A') B $(c 'num notify B')," \
"txt value $(c 'CLI txt value') notify A $(c 'txt notify A') B $(c 'txt notify B'), services released $(c 'All clients established, services released')"
CRASH=$(sed -n '/CLI connected/,$p' "$OUT/client.txt" | grep -a -c -E 'Guru|abort\(\)|Backtrace|rst:0x|task_wdt')
[ "$CRASH" = 0 ] || { echo "FAIL: the client crashed or reset $CRASH times after connecting"; exit 1; }
[ "$(c 'num notify A')" -gt 0 ] && [ "$(c 'txt notify A')" -gt 0 ] || { echo "FAIL: no on_notify fired"; exit 1; }
[ "$(c 'txt notify B')" -gt 0 ] || { echo "FAIL: the delayed txt on_notify never fired"; exit 1; }
[ "$(c 'num notify A')" = "$(c 'num notify B')" ] || { echo "FAIL: the two num on_notify triggers fired a different number of times"; exit 1; }
# the 1 s delay can push the last txt notify B past the end of the capture
TD=$(($(c 'txt notify A') - $(c 'txt notify B')))
[ "$TD" -ge 0 ] && [ "$TD" -le 1 ] || { echo "FAIL: txt notify A and B differ by $TD"; exit 1; }
[ "$(c 'All clients established, services released')" -gt 0 ] || { echo "FAIL: services were never released (#21821)"; exit 1; }
echo PASS
.agents/skills/hardware-test/scripts/ble_notify/server.yaml
+64
View File
@@ -0,0 +1,64 @@
# GATT server (ESP32-S3): a numeric and a text characteristic notify every 2 s; every 5th round is empty
esphome:
name: ${name}
esp32:
variant: esp32s3
board: esp32-s3-devkitc-1
framework:
type: esp-idf
logger:
level: DEBUG
hardware_uart: USB_SERIAL_JTAG
esp32_ble:
name: ${name}
esp32_ble_server:
on_connect:
- logger.log: {format: "SRV connected", level: INFO}
on_disconnect:
- logger.log: {format: "SRV disconnected", level: INFO}
services:
- uuid: 5ec10000-0000-1000-8000-00805f9b34fb
advertise: true
characteristics:
- id: numc
uuid: 5ec10001-0000-1000-8000-00805f9b34fb
read: true
notify: true
value: [0]
- id: txtc
uuid: 5ec10002-0000-1000-8000-00805f9b34fb
read: true
notify: true
value: "t0"
globals:
- {id: cnt, type: int, initial_value: "0"}
interval:
- interval: 2s
then:
- lambda: |-
int n = ++id(cnt);
if (n % 5 == 0) {
id(numc)->set_value(std::vector<uint8_t>{});
id(txtc)->set_value(std::vector<uint8_t>{});
ESP_LOGI("srv", "SRV sent %d empty", n);
} else if (n % 5 == 3) {
// uint16 format byte: 0x06, value n * 100 big endian
uint16_t v = n * 100;
id(numc)->set_value(std::vector<uint8_t>{0x06, (uint8_t) (v >> 8), (uint8_t) v});
std::string t = "text-" + std::to_string(n) + "-long-enough-to-matter";
id(txtc)->set_value(t);
ESP_LOGI("srv", "SRV sent %d num=%u txt=%s", n, v, t.c_str());
} else {
id(numc)->set_value(std::vector<uint8_t>{(uint8_t) n});
std::string t = "t" + std::to_string(n);
id(txtc)->set_value(t);
ESP_LOGI("srv", "SRV sent %d num=%d txt=%s", n, n & 0xFF, t.c_str());
}
id(numc)->notify();
id(txtc)->notify();
.agents/skills/hardware-test/scripts/ble_server_security/bonds.hpp
+25
View File
@@ -0,0 +1,25 @@
#pragma once
#include <esp_err.h>
#include <esp_gap_ble_api.h>
#include "esphome/core/helpers.h"
#include "esphome/core/log.h"
// Logs the bond list Bluedroid loaded from NVS
inline void log_bonds(const char *who) {
int n = esp_ble_get_bond_device_num();
esp_ble_bond_dev_t list[8];
int len = n > 8 ? 8 : n;
if (len > 0) {
esp_err_t err = esp_ble_get_bond_device_list(&len, list);
if (err != ESP_OK) {
ESP_LOGW("bonds", "%s: %d bonded, bond list failed: %s", who, n, esp_err_to_name(err));
return;
}
}
ESP_LOGI("bonds", "%s: %d bonded", who, n);
for (int i = 0; i < len; i++) {
char mac[esphome::MAC_ADDRESS_PRETTY_BUFFER_SIZE];
const uint8_t *k = list[i].bond_key.penc_key.ltk;
ESP_LOGI("bonds", "%s: bond %d %s key_mask=%02x ltk=%02x%02x..%02x%02x", who, i,
esphome::format_mac_addr_upper(list[i].bd_addr, mac), list[i].bond_key.key_mask, k[0], k[1], k[14], k[15]);
}
}
.agents/skills/hardware-test/scripts/ble_server_security/client.yaml
+156
View File
@@ -0,0 +1,156 @@
# Waveshare ESP32-S3 (any ESP32 with BLE) as the central. run.sh passes name, io, auth, idf and server (the
# server's BLE MAC from its esp32_ble dump) with -s. ble_client never pairs by itself: the Pair button calls pair().
esphome:
name: ${name}
esp32:
board: esp32-s3-devkitc-1
variant: esp32s3
flash_size: 16MB
framework:
type: esp-idf
version: ${idf}
logger:
hardware_uart: USB_SERIAL_JTAG
level: VERBOSE
logs:
esp32_ble_tracker: DEBUG
api: DEBUG
api.connection: DEBUG
api.service: DEBUG
api.socket: DEBUG
scheduler: DEBUG
component: DEBUG
wifi: DEBUG
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
api:
reboot_timeout: 0s
ota:
- platform: esphome
esp32_ble:
io_capability: ${io}
auth_req_mode: ${auth}
esp32_ble_tracker:
ble_client:
- mac_address: ${server}
id: cli
on_connect:
- logger.log: "CLI connected"
on_disconnect:
- logger.log: "CLI disconnected"
on_numeric_comparison_request:
- logger.log:
format: "CLI numeric comparison %06u"
args: ["(unsigned) passkey"]
- ble_client.numeric_comparison_reply:
id: cli
accept: true
text_sensor:
- platform: ble_client
ble_client_id: cli
id: secure_value
name: Secure value
service_uuid: "180F"
characteristic_uuid: "2A19"
update_interval: never
on_value:
- logger.log:
format: "CLI secure read: %s"
args: ["x.c_str()"]
- platform: ble_client
ble_client_id: cli
id: open_value
name: Open value
service_uuid: 5ec50000-0000-4000-8000-00000000f000
characteristic_uuid: 5ec50000-0000-4000-8000-00000000f001
update_interval: never
on_value:
- logger.log:
format: "CLI open read: %s"
args: ["x.c_str()"]
- platform: ble_client
ble_client_id: cli
id: mitm_value
name: Mitm value
service_uuid: 5ec50000-0000-4000-8000-00000000f000
characteristic_uuid: 5ec50000-0000-4000-8000-00000000f004
update_interval: never
on_value:
- logger.log:
format: "CLI mitm read: %s"
args: ["x.c_str()"]
- platform: ble_client
ble_client_id: cli
id: notify_value
name: Notify value
service_uuid: 5ec50000-0000-4000-8000-00000000f000
characteristic_uuid: 5ec50000-0000-4000-8000-00000000f003
notify: true
on_value:
- logger.log:
format: "CLI notification: %s"
args: ["x.c_str()"]
button:
- platform: template
name: Subscribe
on_press:
- lambda: |-
// ble_client drops its service list after discovery; ESP-IDF's GATT server puts the CCCD right after
// the characteristic value, so write handle + 1
uint16_t chr = id(notify_value)->handle;
if (chr == 0) { ESP_LOGW("CLI", "notify characteristic handle unknown"); return; }
auto reg = esp_ble_gattc_register_for_notify(id(cli)->get_gattc_if(), id(cli)->get_remote_bda(), chr);
if (reg != ESP_OK) { ESP_LOGW("CLI", "register_for_notify failed: %d", reg); return; }
uint8_t on[2] = {1, 0};
auto err = esp_ble_gattc_write_char_descr(id(cli)->get_gattc_if(), id(cli)->get_conn_id(), chr + 1, 2, on,
ESP_GATT_WRITE_TYPE_RSP, ESP_GATT_AUTH_REQ_NONE);
ESP_LOGI("CLI", "CCCD write to handle %u (char %u) sent, err %d", chr + 1, chr, err);
- platform: template
name: Pair
on_press:
- lambda: 'ESP_LOGI("CLI", "pair() returned %d", (int) id(cli)->pair());'
- platform: template
name: Read secure
on_press:
- component.update: secure_value
- platform: template
name: Read mitm
on_press:
- component.update: mitm_value
- platform: template
name: Read open
on_press:
- component.update: open_value
- platform: template
name: Write secure
on_press:
- ble_client.ble_write:
id: cli
service_uuid: 5ec50000-0000-4000-8000-00000000f000
characteristic_uuid: 5ec50000-0000-4000-8000-00000000f002
value: [0x68, 0x65, 0x6C, 0x6C, 0x6F]
- platform: template
name: Disconnect
on_press:
- ble_client.disconnect: cli
- platform: template
name: Connect
on_press:
- ble_client.connect: cli
- platform: template
name: Remove bond
on_press:
- ble_client.remove_bond:
id: cli
.agents/skills/hardware-test/scripts/ble_server_security/drive.py
+60
View File
@@ -0,0 +1,60 @@
"""Press the client's buttons in order and log every client line about BLE security.
usage: drive.py CLIENT_HOST OUT STEP... STEP: a button name, or wait:SECONDS env: API_KEY
"""
import asyncio
import os
import pathlib
import re
import sys
import time
from aioesphomeapi import APIClient, ButtonInfo, LogLevel
HOST, OUT, STEPS = sys.argv[1], sys.argv[2], sys.argv[3:]
LOG = pathlib.Path(OUT).open("w", encoding="utf-8") # noqa: SIM115 open for the whole run
PATTERN = re.compile(
r"CLI|ble_client|ble_text_sensor|esp32_ble_client|[Aa]uth|[Ee]ncrypt|[Bb]ond|Error|status=|pair"
)
def note(s: str) -> None:
line = f"{time.strftime('%H:%M:%S')} {s}"
print(line)
LOG.write(line + "\n")
LOG.flush()
async def main() -> None:
c = APIClient(HOST, 6053, None, noise_psk=os.environ.get("API_KEY"))
for attempt in range(40):
try:
await c.connect(login=True)
break
except Exception as err: # noqa: BLE001
last_err = err
note(f"connect attempt {attempt + 1} failed: {err!r}")
await asyncio.sleep(2)
else:
raise last_err
ents, _ = await c.list_entities_services()
btn = {e.name: e.key for e in ents if isinstance(e, ButtonInfo)}
def on_log(m) -> None:
t = re.sub(r"\x1b\[[0-9;]*m", "", m.message.decode(errors="replace"))
if PATTERN.search(t):
note("LOG " + t.strip().replace("\n", " | "))
c.subscribe_logs(on_log, log_level=LogLevel.LOG_LEVEL_DEBUG)
for step in STEPS:
if step.startswith("wait:"):
await asyncio.sleep(float(step[5:]))
continue
note(f"PRESS {step}")
c.button_command(btn[step])
await asyncio.sleep(4)
await c.disconnect()
asyncio.run(main())
.agents/skills/hardware-test/scripts/ble_server_security/esp32central-cli.yaml
+92
View File
@@ -0,0 +1,92 @@
# Bonding GATT client (classic ESP32): connects to esp32central-srv.yaml, cycles the link every 40 s.
# Substitutions: name, server (the server's BLE MAC from its esp32_ble dump).
esphome:
name: ${name}
includes: [bonds.hpp]
on_boot:
priority: -100
then:
- delay: 2s
- lambda: 'log_bonds("client");'
esp32:
board: esp32dev
framework:
type: esp-idf
logger:
level: DEBUG
esp32_ble:
io_capability: display_yes_no
auth_req_mode: sc_mitm_bond
esp32_ble_tracker:
ble_client:
- mac_address: ${server}
id: c
on_connect:
- logger.log: {format: "CLI connected", level: INFO}
# Start encryption like a phone does after an insufficient authentication reply
- lambda: |-
esp_err_t err = esp_ble_set_encryption(id(c).get_remote_bda(), ESP_BLE_SEC_ENCRYPT_MITM);
ESP_LOGI("main", "CLI set_encryption %d", (int) err);
on_disconnect:
- logger.log: {format: "CLI disconnected", level: INFO}
on_numeric_comparison_request:
- logger.log: {format: "CLI numeric comparison %06u", args: ["(unsigned) passkey"], level: INFO}
- ble_client.numeric_comparison_reply:
id: c
accept: true
on_passkey_request:
- logger.log: {format: "CLI passkey request", level: INFO}
text_sensor:
- platform: ble_client
ble_client_id: c
name: plain
on_value:
- logger.log: {format: "CLI value plain %s", args: ['x.c_str()'], level: INFO}
service_uuid: 5ec00000-0000-1000-8000-00805f9b34fb
characteristic_uuid: 5ec00001-0000-1000-8000-00805f9b34fb
update_interval: 7s
- platform: ble_client
ble_client_id: c
name: encrypted
on_value:
- logger.log: {format: "CLI value encrypted %s", args: ['x.c_str()'], level: INFO}
service_uuid: 5ec00000-0000-1000-8000-00805f9b34fb
characteristic_uuid: 5ec00002-0000-1000-8000-00805f9b34fb
update_interval: 7s
- platform: ble_client
ble_client_id: c
name: mitm
on_value:
- logger.log: {format: "CLI value mitm %s", args: ['x.c_str()'], level: INFO}
service_uuid: 5ec00000-0000-1000-8000-00805f9b34fb
characteristic_uuid: 5ec00003-0000-1000-8000-00805f9b34fb
update_interval: 7s
- platform: ble_client
ble_client_id: c
name: notified
on_value:
- logger.log: {format: "CLI value notified %s", args: ['x.c_str()'], level: INFO}
service_uuid: 5ec00000-0000-1000-8000-00805f9b34fb
characteristic_uuid: 5ec00004-0000-1000-8000-00805f9b34fb
notify: true
interval:
- interval: 40s
startup_delay: 40s
then:
- ble_client.ble_write:
id: c
service_uuid: 5ec00000-0000-1000-8000-00805f9b34fb
characteristic_uuid: 5ec00003-0000-1000-8000-00805f9b34fb
value: [0x01, 0x02, 0x03]
- delay: 2s
- logger.log: {format: "CLI cycling link", level: INFO}
- lambda: 'id(c).set_enabled(false);'
- delay: 3s
- lambda: 'id(c).set_enabled(true);'
.agents/skills/hardware-test/scripts/ble_server_security/esp32central-flow.sh
Executable
+38
View File
@@ -0,0 +1,38 @@
#!/bin/bash
# esp32central-flow.sh TAG: erase both boards, flash esp32central-srv.yaml (SERVER_PORT, from SERVER_TREE) and
# esp32central-cli.yaml (CLIENT_PORT, from TREE), then
# A: capture a fresh pairing and three link cycles (170 s)
# B: reset both together so each loads its bond from NVS, capture 130 s
# and count pairings, bond reuse and dropped bonds per phase. Logs go to out-ec<TAG>/. PASS when phase A read the MITM
# characteristic and phase B read it on the stored bond (no numeric comparison, no "Deleting unpaired device").
# env: TREE, SERVER_TREE (checkout with #17562, default TREE), SERVER_PORT, CLIENT_PORT, SERVER_BLE_MAC (from the
# server's esp32_ble dump), SC (path to serial_capture.py), PY (checkout python)
D=$(cd "$(dirname "$0")" && pwd); G=${1:?tag}; T=${TREE:?set TREE}; ST=${SERVER_TREE:-$T}; PY=${PY:-$T/venv/bin/python}
S=${SERVER_PORT:?set SERVER_PORT}; C=${CLIENT_PORT:?set CLIENT_PORT}; MAC=${SERVER_BLE_MAC:?set SERVER_BLE_MAC}; SC=${SC:?set SC}
O=$D/out-ec$G; rm -rf "$O"; mkdir -p "$O"
pkill -f "[s]erial_capture.py $S"; pkill -f "[s]erial_capture.py $C"
$PY -m esptool --port "$S" erase_flash > "$O/erase-srv.log" 2>&1 & E=$!
$PY -m esptool --port "$C" erase_flash > "$O/erase-cli.log" 2>&1 && wait $E || { echo "FAIL: erase"; exit 1; }
(cd "$ST" && $PY -m esphome -s name "ecsrv$G" run --no-logs "$D/esp32central-srv.yaml" --device "$S" > "$O/srv-upload.log" 2>&1) ||
{ echo "FAIL: server build or upload"; exit 1; }
(cd "$T" && $PY -m esphome -s name "eccli$G" -s server "$MAC" run --no-logs "$D/esp32central-cli.yaml" --device "$C" \
> "$O/cli-upload.log" 2>&1) || { echo "FAIL: client build or upload"; exit 1; }
phase() { # phase NAME SECONDS
$PY "$SC" "$S" "$2" "$O/$1-srv.txt" --ms --reset > /dev/null 2>&1 & local cap=$!
sleep 2
$PY "$SC" "$C" "$(($2 - 2))" "$O/$1-cli.txt" --ms --reset > /dev/null 2>&1
wait $cap
[ -s "$O/$1-srv.txt" ] && [ -s "$O/$1-cli.txt" ] || { echo "FAIL: phase $1 capture empty"; exit 1; }
local f=$O/$1-cli.txt
echo "$G $1: connects $(grep -a -c 'CLI connected' "$f"), numeric comparisons $(grep -a -c 'CLI numeric comparison' "$f")," \
"mitm reads $(grep -a -c 'CLI value mitm' "$f"), server writes $(grep -a -c 'SRV mitm write' "$O/$1-srv.txt")," \
"unpaired deletes cli $(grep -a -c 'Deleting unpaired device' "$f") srv $(grep -a -c 'Deleting unpaired device' "$O/$1-srv.txt")"
grep -a -h '\[bonds' "$O/$1-srv.txt" "$f" | sed 's/.*\]: //'
}
phase A 170
phase B 130
grep -a -q 'CLI value mitm' "$O/A-cli.txt" || { echo "FAIL: the client never read the MITM characteristic"; exit 1; }
grep -a -q 'CLI value mitm' "$O/B-cli.txt" || { echo "FAIL: phase B never read the MITM characteristic"; exit 1; }
NB=$(grep -a -c 'CLI numeric comparison' "$O/B-cli.txt"); UB=$(cat "$O/B-cli.txt" "$O/B-srv.txt" | grep -a -c 'Deleting unpaired device')
[ "$NB" = 0 ] && [ "$UB" = 0 ] || { echo "FAIL: phase B paired again ($NB numeric comparisons, $UB unpaired deletes)"; exit 1; }
echo PASS
.agents/skills/hardware-test/scripts/ble_server_security/esp32central-srv.yaml
+78
View File
@@ -0,0 +1,78 @@
# Secure GATT server (ESP32-S3, #17562): plain, encrypted, MITM read+write and an encrypted notify characteristic.
# Numeric comparison is accepted automatically. Substitution: name.
esphome:
name: ${name}
includes: [bonds.hpp]
on_boot:
priority: -100
then:
- delay: 2s
- lambda: 'log_bonds("server");'
esp32:
board: esp32-s3-devkitc-1
variant: esp32s3
flash_size: 8MB
framework:
type: esp-idf
logger:
level: DEBUG
hardware_uart: UART0
esp32_ble:
name: ${name}
io_capability: display_yes_no
auth_req_mode: sc_mitm_bond
esp32_ble_server:
id: srv
on_connect:
- logger.log: {format: "SRV connected", level: INFO}
on_disconnect:
- logger.log: {format: "SRV disconnected", level: INFO}
on_numeric_comparison_request:
- logger.log: {format: "SRV numeric comparison %06u", args: ["(unsigned) passkey"], level: INFO}
- ble_server.numeric_comparison_reply:
id: srv
address: !lambda return address;
accept: true
on_passkey_request:
- logger.log: {format: "SRV passkey request", level: INFO}
services:
- uuid: 5ec00000-0000-1000-8000-00805f9b34fb
advertise: true
characteristics:
- uuid: 5ec00001-0000-1000-8000-00805f9b34fb
read: true
value: "plain"
- uuid: 5ec00002-0000-1000-8000-00805f9b34fb
read: true
read_encrypt: true
value: "encrypted"
- uuid: 5ec00003-0000-1000-8000-00805f9b34fb
read: true
read_encrypt_mitm: true
write: true
write_encrypt_mitm: true
value: "mitm"
on_write:
- logger.log: {format: "SRV mitm write %s", args: ['format_hex_pretty(x.data(), x.size()).c_str()'], level: INFO}
- id: notify_char
uuid: 5ec00004-0000-1000-8000-00805f9b34fb
read: false
notify: true
read_encrypt: true
value: "n0"
globals:
- {id: cnt, type: int, initial_value: "0"}
interval:
- interval: 5s
then:
- lambda: 'id(cnt)++;'
- ble_server.characteristic.set_value:
id: notify_char
value: !lambda 'auto s = "n" + std::to_string(id(cnt)); return std::vector<uint8_t>(s.begin(), s.end());'
- ble_server.characteristic.notify:
id: notify_char
.agents/skills/hardware-test/scripts/ble_server_security/run.sh
Executable
+33
View File
@@ -0,0 +1,33 @@
#!/bin/bash
# usage: run.sh TAG IO AUTH build and flash the server (serial) and the client (OTA), then pair once and reconnect twice
# Copy this directory into a scratch directory with a secrets.yaml (wifi_ssid, wifi_password) and run it there.
# IO/AUTH: none bond (Just Works) or display_yes_no sc_mitm_bond (numeric comparison, MITM).
# env: TREE (esphome checkout for the client), SERVER_TREE (checkout with esp32_ble_server security, #17562 or
# later; default TREE), SERVER_PORT (devkit serial port), CLIENT_HOST (client address), SERVER_BLE_MAC (from the
# server's esp32_ble dump), SC (path to serial_capture.py), IDF (default recommended), PY (default $TREE/venv/bin/python)
# A server keeps its bonds in NVS and refuses a weaker re-pairing: erase its flash before switching from nc to jw.
D=$(cd "$(dirname "$0")" && pwd); G=${1:?tag}; IO=${2:?io}; AUTH=${3:?auth}; T=${TREE:?set TREE}; PY=${PY:-$T/venv/bin/python}
P=${SERVER_PORT:?set SERVER_PORT}; C=${CLIENT_HOST:?set CLIENT_HOST}; MAC=${SERVER_BLE_MAC:?set SERVER_BLE_MAC}; SC=${SC:?set SC}
E=(-s io "$IO" -s auth "$AUTH" -s idf "${IDF:-recommended}")
ST=${SERVER_TREE:-$T}
build() { local t=$1; shift; (cd "$t" && PYTHONUNBUFFERED=1 timeout 1800 $PY -m esphome "$@"); }
ok=
for i in 1 2 3; do
build "$ST" -s name "bss-$G" "${E[@]}" run --no-logs "$D/server.yaml" --device "$P" > "$D/server-$G-upload.log" 2>&1 && ok=1 && break
sleep 5
done
[ -n "$ok" ] || { echo "FAIL: server build or flash (does SERVER_TREE have #17562?)"; exit 1; }
build "$T" -s name "bsc-$G" "${E[@]}" -s server "$MAC" run --no-logs "$D/client.yaml" --device "$C" > "$D/client-$G-upload.log" 2>&1 ||
{ echo "FAIL: client build or upload"; exit 1; }
rm -f "$D/server-$G.txt"
$PY "$SC" "$P" 330 "$D/server-$G.txt" --reset > /dev/null 2>&1 & CAP=$!
trap 'kill $CAP 2>/dev/null' EXIT
sleep 25
R=("Disconnect" "wait:3" "Connect" "wait:10" "Pair" "wait:5" "Read secure" "Read mitm")
$PY "$D/drive.py" "$C" "$D/client-$G.txt" "wait:6" "Remove bond" "Disconnect" "wait:3" "Connect" "wait:10" \
"Read secure" "Read mitm" "Write secure" "Subscribe" "wait:8" "Pair" "wait:6" "Read secure" "Read mitm" "Write secure" \
"Subscribe" "wait:10" "${R[@]}" "${R[@]}" > /dev/null || { echo "FAIL: driver"; exit 1; }
wait $CAP; CAPRC=$?; trap - EXIT
[ "$CAPRC" = 0 ] && [ -s "$D/server-$G.txt" ] || { echo "FAIL: server capture failed or empty (rc $CAPRC)"; exit 1; }
MODE=jw; [ "$IO" = none ] || MODE=nc
$PY "$D/summary.py" "$MODE" "$D/client-$G.txt" "$D/server-$G.txt"
.agents/skills/hardware-test/scripts/ble_server_security/server.yaml
+85
View File
@@ -0,0 +1,85 @@
# Classic ESP32 devkit as the secure GATT server. run.sh passes name, io (none or display_yes_no),
# auth (bond or sc_mitm_bond) and idf (recommended, or a version such as 5.5.5) with -s.
# Needs esp32_ble_server security from #17562 (read_encrypt, numeric comparison); build it with SERVER_TREE.
esphome:
name: ${name}
esp32:
board: esp32dev
framework:
type: esp-idf
version: ${idf}
logger:
level: DEBUG
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
api:
reboot_timeout: 0s
ota:
- platform: esphome
esp32_ble:
io_capability: ${io}
auth_req_mode: ${auth}
esp32_ble_server:
id: srv
on_connect:
- logger.log: "SRV client connected"
on_disconnect:
- logger.log: "SRV client disconnected"
on_numeric_comparison_request:
- logger.log:
format: "SRV numeric comparison %06u"
args: ["(unsigned) passkey"]
- ble_server.numeric_comparison_reply:
id: srv
address: !lambda return address;
accept: true
services:
- uuid: "180F"
characteristics:
- uuid: "2A19"
read: true
read_encrypt: true
value:
data: "99.9"
- uuid: 5ec50000-0000-4000-8000-00000000f000
characteristics:
- uuid: 5ec50000-0000-4000-8000-00000000f001
read: true
value:
data: "open"
- uuid: 5ec50000-0000-4000-8000-00000000f002
write: true
write_encrypt: true
on_write:
- lambda: 'ESP_LOGI("SRV", "secure write received: %s", std::string(x.begin(), x.end()).c_str());'
- uuid: 5ec50000-0000-4000-8000-00000000f004
read: true
read_encrypt_mitm: true
value:
data: "mitm"
- uuid: 5ec50000-0000-4000-8000-00000000f003
id: secure_notify
read: true
read_encrypt: true
notify: true
value:
data: "n0"
interval:
- interval: 2s
then:
- lambda: |-
static int n = 0;
char buf[12];
snprintf(buf, sizeof(buf), "n%d", ++n);
id(secure_notify)->set_value((const uint8_t *) buf, strlen(buf));
- ble_server.characteristic.notify:
id: secure_notify
.agents/skills/hardware-test/scripts/ble_server_security/summary.py
+80
View File
@@ -0,0 +1,80 @@
"""Judge one run.sh run from the client log (drive.py output) and the server's serial capture.
usage: summary.py MODE CLIENT_LOG SERVER_CAPTURE MODE: jw (Just Works) or nc (numeric comparison, MITM)
Before the first Pair: the encrypted and MITM reads must each be tried and refused (an `Error reading char` reply),
no notification may arrive and no encrypted write may reach the server. After it: the encrypted read returns 99.9,
exactly one write (the paired one) reaches the server, the second Subscribe brings notifications, and the MITM-only
characteristic is readable only after an nc pairing. Prints the reconnect pattern and PASS or FAIL.
"""
import pathlib
import re
import sys
MODE = sys.argv[1]
cli = pathlib.Path(sys.argv[2]).read_text(encoding="utf-8").splitlines()
srv = re.sub(
r"\x1b\[[0-9;]*m",
"",
pathlib.Path(sys.argv[3]).read_bytes().decode(errors="replace"),
)
pair_at = next((i for i, line in enumerate(cli) if "PRESS Pair" in line), None)
if pair_at is None:
sys.exit("FAIL: no Pair step in the client log")
before, after = cli[:pair_at], cli[pair_at:]
subs = [i for i, line in enumerate(after) if "PRESS Subscribe" in line]
after_sub = after[subs[0] :] if subs else []
def count(lines: list[str], pat: str) -> int:
return sum(1 for line in lines if re.search(pat, line))
def outcome(lines: list[str], button: str, ok_pat: str) -> str:
"""'ok', 'refused' or 'none' for the first press of BUTTON.
The window runs to the next read, pair or connection step, since a reply can come after a write press. A value
wins over an error line: the error can belong to another characteristic read in the same window.
"""
start = next((i for i, line in enumerate(lines) if f"PRESS {button}" in line), None)
if start is None:
return "none"
window = []
for line in lines[start + 1 :]:
if re.search(r"PRESS (Read|Pair|Disconnect|Connect|Subscribe|Remove)", line):
break
window.append(line)
if any(re.search(ok_pat, line) for line in window):
return "ok"
return "refused" if any("Error reading char" in line for line in window) else "none"
secure_before = outcome(before, "Read secure", r"secure read: 9")
mitm_before = outcome(before, "Read mitm", r"mitm read: m")
mitm_after = outcome(after, "Read mitm", r"mitm read: m")
writes = srv.count("secure write received")
checks = {
f"encrypted read refused before pairing ({secure_before})": secure_before
== "refused",
f"MITM read refused before pairing ({mitm_before})": mitm_before == "refused",
"no notifications before pairing": count(before, r"notification: n") == 0,
"encrypted read after pairing": outcome(after, "Read secure", r"secure read: 99\.9")
== "ok",
# one Write secure press before Pair (must be refused) and one after it
f"only the paired write reached the server ({writes})": writes == 1,
"notifications after subscribing paired": count(after_sub, r"notification: n") > 0,
}
if MODE == "nc":
checks[f"MITM read after nc pairing ({mitm_after})"] = mitm_after == "ok"
else:
checks[f"MITM read still refused after Just Works ({mitm_after})"] = (
mitm_after == "refused"
)
for name, ok in checks.items():
print(f"{'ok ' if ok else 'FAIL'} {name}")
print(
f"server: {srv.count('Authentication complete')} authentications, {srv.count('SRV numeric comparison')} numeric "
f"comparisons, {srv.count('Deleting unpaired device')} bonds dropped by the stack"
)
print("PASS" if all(checks.values()) else "FAIL")
sys.exit(0 if all(checks.values()) else 1)
.agents/skills/hardware-test/scripts/ble_terminate/an.py
+90
View File
@@ -0,0 +1,90 @@
"""Match each proxy disconnect with the peer's own disconnect line and count the links the peer kept.
Usage: an.py DIR LABEL [ROUNDS] reads LABEL-drive.txt, LABEL-peer.txt (serial_capture --ms) and LABEL-proxy.txt
(esphome logs, VERBOSE). A round counts only when the last `Conn params updated` the proxy logged since the previous
disconnect shows latency=10; otherwise it is inconclusive. Exits 1 when the peer kept a link past 3 s (the terminate
was lost), a round was inconclusive, or fewer than ROUNDS rounds completed."""
import datetime as dt
from pathlib import Path
import re
import sys
D, label = Path(sys.argv[1]), sys.argv[2]
ROUNDS = int(sys.argv[3]) if len(sys.argv) > 3 else None
def read(name: str) -> list[str]:
return (
(D / f"{label}-{name}.txt")
.read_text(encoding="utf-8", errors="replace")
.splitlines()
)
def ptime(line: str) -> float | None:
"""Seconds since midnight from a leading [HH:MM:SS.mmm] stamp."""
m = re.match(r"\[(\d+):(\d+):(\d+)\.(\d+)\]", line)
return (
int(m[1]) * 3600 + int(m[2]) * 60 + int(m[3]) + int(m[4]) / 1000 if m else None
)
pdisc = [
t
for line in read("peer")
if "PEER DISCONNECT" in line and (t := ptime(line)) is not None
]
params = [
(t, int(m[1]))
for line in read("proxy")
if "Conn params updated" in line
and (m := re.search(r"latency=(\d+)", line))
and (t := ptime(line)) is not None
]
res = []
prev = -1.0
for line in read("drive"):
m = re.search(
r"R(\d+) .*DISC_CALL ([\d.]+) DISC_DONE ([\d.]+) \(\+([\d.]+)s\)", line
)
if not m:
if line.startswith("R"):
print(" ", line)
continue
# Both captures stamp local wall clock time; compare as seconds since midnight.
t = dt.datetime.fromtimestamp(float(m[2])).astimezone()
tc = t.hour * 3600 + t.minute * 60 + t.second + t.microsecond / 1e6
after = [p - tc for p in pdisc if -1 < p - tc < 12]
window = [lat for pt, lat in params if prev < pt <= tc]
res.append(
(
int(m[1]),
float(m[4]),
after[0] if after else None,
window[-1] if window else None,
)
)
prev = tc
for r, done, pd, lat in res:
peer = (
f"peer disconnect +{pd:.2f}s" if pd is not None else "peer disconnect not seen"
)
print(f" R{r:2} central done +{done:.3f}s {peer} latency at disconnect {lat}")
late = sum(1 for _, _, pd, lat in res if lat == 10 and (pd is None or pd > 3))
inconclusive = sum(1 for *_, lat in res if lat != 10)
print(
f"{label}: rounds {len(res)}, peer kept the link (>3 s or not seen) {late}, inconclusive {inconclusive}"
)
failed = []
if not res:
failed.append("no round completed")
if ROUNDS is not None and len(res) < ROUNDS:
failed.append(f"only {len(res)} of {ROUNDS} rounds completed")
if late:
failed.append(f"{late} links kept")
if inconclusive:
failed.append(
f"INCONCLUSIVE: {inconclusive} rounds had no latency=10 update before the disconnect"
)
print(f"PASS: {label}" if not failed else f"FAIL: {label}: " + "; ".join(failed))
sys.exit(1 if failed else 0)
.agents/skills/hardware-test/scripts/ble_terminate/btdrive.py
+100
View File
@@ -0,0 +1,100 @@
"""Connect to the peer through the proxy, read its services, idle, disconnect; print host timestamps per round.
Usage: btdrive.py PROXY KEY PEER_MAC ROUNDS IDLE_S"""
import asyncio
import sys
import time
from aioesphomeapi import APIClient, APIConnectionError
async def main(host: str, key: str, peer: str, rounds: int, idle: float) -> int:
addr = int(peer.replace(":", ""), 16)
cli = APIClient(host, 6053, None, noise_psk=key)
await cli.connect(login=True)
info = await cli.device_info()
print(f"proxy {info.name} bt_mac {info.bluetooth_mac_address}", flush=True)
seen = 0
def adv(msg) -> None:
nonlocal seen
seen += sum(a.address == addr for a in msg.advertisements)
# The proxy only connects to a device its scanner has seen.
cli.subscribe_bluetooth_le_raw_advertisements(adv)
await asyncio.sleep(5)
print(f"peer advertisements seen in 5 s: {seen}", flush=True)
if not seen:
print("FAIL: the proxy does not see the peer", flush=True)
await cli.disconnect()
return 1
done = 0
for r in range(1, rounds + 1):
state: asyncio.Queue = asyncio.Queue()
def cb(
connected: bool, mtu: int, err: int, state: asyncio.Queue = state
) -> None:
state.put_nowait((connected, err, time.time()))
t0 = time.time()
try:
cancel = await cli.bluetooth_device_connect(
addr, cb, timeout=20, address_type=0, feature_flags=0xFF
)
except (APIConnectionError, TimeoutError) as e:
print(f"R{r} CONNECT ERROR {type(e).__name__}", flush=True)
await asyncio.sleep(9)
continue
try:
c, err, t = await asyncio.wait_for(state.get(), 25)
except TimeoutError:
print(f"R{r} CONNECT TIMEOUT", flush=True)
cancel()
await asyncio.sleep(8)
continue
if not c:
print(f"R{r} CONNECT FAIL err {err} after {t - t0:.2f}s", flush=True)
cancel()
await asyncio.sleep(8)
continue
try:
n = len((await cli.bluetooth_gatt_get_services(addr)).services)
except (APIConnectionError, TimeoutError) as e:
n = f"err {e!r}"
await asyncio.sleep(idle)
td = time.time()
await cli.bluetooth_device_disconnect(addr)
try:
c2, err2, t2 = await asyncio.wait_for(state.get(), 15)
if c2 or not isinstance(n, int):
# an unexpected connect state or a failed service read: the round did not run as intended
print(
f"R{r} BAD ROUND services {n} connected {c2} err {err2}", flush=True
)
else:
print(
f"R{r} services {n} DISC_CALL {td:.3f} DISC_DONE {t2:.3f} (+{t2 - td:.3f}s) err {err2}",
flush=True,
)
done += 1
except TimeoutError:
print(
f"R{r} services {n} DISC_CALL {td:.3f} no disconnect state", flush=True
)
cancel()
await asyncio.sleep(
9
) # a peer that missed the terminate hits its 6 s supervision timeout in this gap
await cli.disconnect()
print(f"rounds completed {done} of {rounds}", flush=True)
return 0 if done == rounds else 1
sys.exit(
asyncio.run(
main(
sys.argv[1], sys.argv[2], sys.argv[3], int(sys.argv[4]), float(sys.argv[5])
)
)
)
.agents/skills/hardware-test/scripts/ble_terminate/btpeer.hpp
+17
View File
@@ -0,0 +1,17 @@
#pragma once
#include <cstring>
#include <esp_gap_ble_api.h>
#include "esphome/core/log.h"
#include "central_bda.hpp" // written by run.sh from PROXY_BT_MAC
// 50 ms interval, peripheral latency 10, 6 s supervision timeout
inline void btpeer_request_latency() {
esp_ble_conn_update_params_t p{};
memcpy(p.bda, CENTRAL_BDA, 6);
p.min_int = 40;
p.max_int = 40;
p.latency = 10;
p.timeout = 600;
esp_err_t err = esp_ble_gap_update_conn_params(&p);
ESP_LOGI("peer", "requested interval 50 ms latency 10 timeout 6 s: %d", err);
}
.agents/skills/hardware-test/scripts/ble_terminate/btpeer.yaml
+36
View File
@@ -0,0 +1,36 @@
esphome:
name: btpeer
includes:
- btpeer.hpp
- central_bda.hpp
esp32:
board: esp32dev
framework:
type: esp-idf
logger:
level: VERBOSE
logs:
esp32_ble: VERBOSE
scheduler: DEBUG
component: DEBUG
esp32_ble:
max_connections: 1
esp32_ble_server:
manufacturer: test
on_connect:
- lambda: ESP_LOGI("peer", "PEER CONNECT conn %u", (unsigned) id);
- delay: 4s
- lambda: btpeer_request_latency();
on_disconnect:
- lambda: ESP_LOGI("peer", "PEER DISCONNECT conn %u", (unsigned) id);
services:
- uuid: 6e400001-b5a3-f393-e0a9-e50e24dcca9e
advertise: true
characteristics:
- uuid: 6e400002-b5a3-f393-e0a9-e50e24dcca9e
read: true
value: "peer"
.agents/skills/hardware-test/scripts/ble_terminate/btproxy.yaml
+44
View File
@@ -0,0 +1,44 @@
substitutions:
name: btproxy
esphome:
name: ${name}
esp32:
board: esp32-s3-devkitc-1
variant: esp32s3
flash_size: 16MB
framework:
type: esp-idf
logger:
hardware_uart: USB_SERIAL_JTAG
level: VERBOSE
logs:
scheduler: DEBUG
component: DEBUG
esp32_ble_tracker: DEBUG
ethernet:
type: W5500
clk_pin: GPIO13
mosi_pin: GPIO11
miso_pin: GPIO12
cs_pin: GPIO14
interrupt_pin: GPIO10
reset_pin: GPIO9
api:
encryption:
key: !secret api_key
reboot_timeout: 0s
ota:
- platform: esphome
esp32_ble_tracker:
scan_parameters:
active: false
bluetooth_proxy:
active: true
.agents/skills/hardware-test/scripts/ble_terminate/run.sh
Executable
+31
View File
@@ -0,0 +1,31 @@
#!/bin/bash
# usage: run.sh LABEL ROUNDS build both boards, then ROUNDS connect/disconnect rounds through the proxy
# Copy this directory into a scratch directory with a secrets.yaml (api_key, base64 Noise key) and run it there.
# env: TREE (esphome checkout to build the proxy from), PORT (peer devkit serial port), PROXY (proxy address, flashed
# over the air; the first flash of a fresh board goes over USB), PROXY_BT_MAC (the proxy's Bluetooth MAC, printed by
# btdrive.py as bt_mac), PEER_MAC (the peer's Bluetooth MAC, base MAC + 2 on a classic ESP32), SC (path to
# serial_capture.py), PY (checkout python), PEER_TREE (checkout for the peer, defaults to TREE)
D=$(cd "$(dirname "$0")" && pwd); L=${1:?label}; N=${2:-12}; T=${TREE:?set TREE}; PT=${PEER_TREE:-$T}
P=${PORT:?set PORT}; S3=${PROXY:?set PROXY}; SC=${SC:?set SC}; PY=${PY:-$T/venv/bin/python}
PEER=${PEER_MAC:?set PEER_MAC}; CM=${PROXY_BT_MAC:?set PROXY_BT_MAC}
KEY=$(sed -n 's/^api_key: *"\{0,1\}\([^"]*\)"\{0,1\}$/\1/p' "$D/secrets.yaml")
[ -n "$KEY" ] || { echo "FAIL: no api_key in secrets.yaml"; exit 1; }
cd "$D" || exit 1
printf '#pragma once\n#include <cstdint>\nstatic const uint8_t CENTRAL_BDA[6] = {0x%s};\n' "${CM//:/, 0x}" > central_bda.hpp
(cd "$PT" && PYTHONUNBUFFERED=1 timeout 1500 $PY -m esphome run --no-logs "$D/btpeer.yaml" --device "$P" > "$D/$L-peer-upload.log" 2>&1) \
|| { echo "FAIL: peer build or upload failed"; exit 1; }
(cd "$T" && PYTHONUNBUFFERED=1 timeout 1500 $PY -m esphome run --no-logs "$D/btproxy.yaml" --device "$S3" > "$D/$L-proxy-upload.log" 2>&1) \
|| { echo "FAIL: proxy build or upload failed"; exit 1; }
SECS=$((N * 26 + 40))
pkill -f "[s]erial_capture.py $P"
$PY "$SC" "$P" $SECS "$D/$L-peer.txt" --ms > /dev/null 2>&1 & CAP=$!
(cd "$T" && PYTHONUNBUFFERED=1 exec timeout $((SECS - 10)) $PY -m esphome logs "$D/btproxy.yaml" --device "$S3" > "$D/$L-proxy.txt" 2>&1) & LOGS=$!
trap 'kill $CAP $LOGS 2>/dev/null' EXIT
sleep 6
$PY "$D/btdrive.py" "$S3" "$KEY" "$PEER" "$N" 10 > "$D/$L-drive.txt" 2>&1; RC=$?
sleep 10
kill $CAP $LOGS 2>/dev/null; wait 2>/dev/null; trap - EXIT
[ -s "$D/$L-peer.txt" ] || { tail -3 "$D/$L-drive.txt"; echo "FAIL: peer capture got nothing"; exit 1; }
$PY "$D/an.py" "$D" "$L" "$N"; ARC=$?
[ "$RC" = 0 ] || { tail -1 "$D/$L-drive.txt"; echo "FAIL: driver rc $RC (not every round completed)"; exit 1; }
exit $ARC
.agents/skills/hardware-test/scripts/bluedroid_hex_bench/bench.yaml
+25
View File
@@ -0,0 +1,25 @@
# Runs hex_bench() twice after boot. Needs a tree with esp32_ble/bluedroid_hex.h (#22081).
# Substitutions: name, board (default esp32dev).
substitutions:
board: esp32dev
esphome:
name: ${name}
includes: [hexbench.hpp]
on_boot:
priority: -100
then:
- delay: 3s
- lambda: "hex_bench();"
- delay: 1s
- lambda: "hex_bench();"
esp32:
board: ${board}
framework:
type: esp-idf
logger:
level: DEBUG
esp32_ble:
.agents/skills/hardware-test/scripts/bluedroid_hex_bench/hexbench.hpp
+88
View File
@@ -0,0 +1,88 @@
#pragma once
// Times Bluedroid's sscanf parsing against esphome#22081's replacements on the same inputs.
#include <cctype>
#include <cstdio>
#include <cstring>
#include <esp_cpu.h>
#include "esphome/components/esp32_ble/bluedroid_hex.h"
#include "esphome/core/log.h"
// Bluedroid string_to_bdaddr (bdaddr.c)
static bool __attribute__((noinline)) ref_bdaddr(const char *string, uint8_t *addr) {
unsigned int p[6];
bool ok = sscanf(string, "%02x:%02x:%02x:%02x:%02x:%02x", &p[0], &p[1], &p[2], &p[3], &p[4], &p[5]) == 6;
if (ok)
for (int i = 0; i < 6; i++)
addr[i] = (uint8_t) p[i];
return ok;
}
// Bluedroid btc_config_get_bin decode loop (btc_config.c), after its length and hex checks
static bool __attribute__((noinline)) ref_bin(const char *str, size_t len, uint8_t *value, size_t *length) {
if (len % 2 || len / 2 > *length)
return false;
for (size_t i = 0; i < len; i++)
if (!isxdigit((unsigned char) str[i]))
return false;
for (size_t i = 0; i < len / 2; i++) {
unsigned int val;
sscanf(str + i * 2, "%02x", &val);
value[i] = (uint8_t) val;
}
*length = len / 2;
return true;
}
static bool __attribute__((noinline)) new_bdaddr(const char *s, uint8_t *a) {
return esphome::esp32_ble::parse_bdaddr(s, a);
}
static bool __attribute__((noinline)) new_bin(const char *s, size_t n, uint8_t *v, size_t *l) {
return esphome::esp32_ble::parse_config_bin(s, n, v, l);
}
inline void hex_bench() {
static constexpr const char *ADDRS[] = {"12:34:56:78:9A:BC", "aa:bb:cc:dd:ee:ff", "1:2:3:4:5:6", "00:11:22:33:44:5G"};
// LTK (16 bytes), IRK (16), a 28 byte bonding blob
static constexpr const char *BINS[] = {"00112233445566778899aabbccddeeff", "F0E1D2C3B4A5968778695A4B3C2D1E0F",
"0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c"};
const int n = 2000;
int mism = 0;
for (const char *s : ADDRS) {
uint8_t a[6] = {}, b[6] = {};
bool ra = ref_bdaddr(s, a), rb = new_bdaddr(s, b);
if (ra != rb || (ra && memcmp(a, b, 6) != 0)) {
mism++;
ESP_LOGW("bench", "bdaddr mismatch on %s: ref %d new %d", s, ra, rb);
}
uint32_t t0 = esp_cpu_get_cycle_count();
for (int i = 0; i < n; i++)
ref_bdaddr(s, a);
uint32_t t1 = esp_cpu_get_cycle_count();
for (int i = 0; i < n; i++)
new_bdaddr(s, b);
uint32_t t2 = esp_cpu_get_cycle_count();
ESP_LOGI("bench", "bdaddr %-17s ok=%d sscanf %5u cycles, new %4u cycles", s, (int) rb, (unsigned) ((t1 - t0) / n),
(unsigned) ((t2 - t1) / n));
}
for (const char *s : BINS) {
uint8_t a[32] = {}, b[32] = {};
size_t la = 32, lb = 32, len = strlen(s);
bool ra = ref_bin(s, len, a, &la), rb = new_bin(s, len, b, &lb);
if (ra != rb || la != lb || memcmp(a, b, la) != 0) {
mism++;
ESP_LOGW("bench", "bin mismatch on %s", s);
}
uint32_t t0 = esp_cpu_get_cycle_count();
for (int i = 0; i < n; i++) {
la = 32;
ref_bin(s, len, a, &la);
}
uint32_t t1 = esp_cpu_get_cycle_count();
for (int i = 0; i < n; i++) {
lb = 32;
new_bin(s, len, b, &lb);
}
uint32_t t2 = esp_cpu_get_cycle_count();
ESP_LOGI("bench", "bin %2u bytes sscanf %5u cycles, new %4u cycles", (unsigned) lb, (unsigned) ((t1 - t0) / n),
(unsigned) ((t2 - t1) / n));
}
ESP_LOGI("bench", "DONE mismatches=%d", mism);
}
.agents/skills/hardware-test/scripts/bluedroid_hex_bench/run.sh
Executable
+13
View File
@@ -0,0 +1,13 @@
#!/bin/bash
# run.sh LABEL: build bench.yaml as hb<LABEL> from TREE, flash it over PORT, capture 25 s and print the cycle counts.
# Fails when a parser result differs from Bluedroid's sscanf parsing or the bench never finished.
# env: TREE (checkout with #22081), PORT, SC (path to serial_capture.py), PY (checkout python), BOARD (default esp32dev)
R=$(cd "$(dirname "$0")" && pwd); L=${1:?label}; T=${TREE:?set TREE}; P=${PORT:?set PORT}
PY=${PY:-$T/venv/bin/python}; SC=${SC:?set SC}; OUT=$R/out-hb$L; rm -rf "$OUT"; mkdir -p "$OUT"
pkill -f "[s]erial_capture.py $P"
(cd "$T" && $PY -m esphome -s name "hb$L" -s board "${BOARD:-esp32dev}" run --no-logs "$R/bench.yaml" --device "$P" \
> "$OUT/upload.log" 2>&1) || { echo "FAIL: build or upload"; exit 1; }
$PY "$SC" "$P" 25 "$OUT/serial.txt" --reset > /dev/null 2>&1 || { echo "FAIL: capture got nothing"; exit 1; }
grep -a '\[bench' "$OUT/serial.txt" | sed 's/.*\]: //'
[ "$(grep -a -c 'DONE mismatches=0' "$OUT/serial.txt")" -ge 2 ] || { echo "FAIL: missing DONE or a mismatch"; exit 1; }
echo PASS
.agents/skills/hardware-test/scripts/bluetooth_proxy_half_open/cases.sh
Executable
+71
View File
@@ -0,0 +1,71 @@
#!/bin/bash
# cases.sh PROXY_HOST LABEL [swap]: half-open API session cases against a proxy that already runs the build under
# test (proxy.yaml) and the peripheral (peripheral.yaml). Captures both serial logs with millisecond stamps into
# out-ho<LABEL>/ and runs:
# C owner client killed (socket closed), new client after 4 s, watched 60 s
# H owner frozen with SIGSTOP (socket stays open, no FIN), new client after 4 s, watched 300 s, then it asks the
# proxy to connect to the peripheral and releases it
# N owner frozen and nobody reconnects for 200 s, then watched 40 s
# With swap it instead runs case H three times, the new client asking for the held peripheral right after it
# subscribes (ha.py swap) and retrying on the first advert, with logs in out-ho<LABEL>-4/. PASS when every case's
# observer saw the peripheral advertise (the held link was released) or every swap round connected.
# env: PROXY_PORT, PERI_PORT (serial ports), SC (path to serial_capture.py), PY (python with aioesphomeapi),
# API_KEY (the proxy's api key, - for plaintext)
D=$(cd "$(dirname "$0")" && pwd); H=${1:?proxy host}; L=${2:?label}; MODE=${3:-cases}; PY=${PY:-python3}
SC=${SC:?set SC}
PP=${PROXY_PORT:?set PROXY_PORT}; QP=${PERI_PORT:?set PERI_PORT}; KEY=${API_KEY:?set API_KEY}
case $MODE in
cases) O=$D/out-ho$L; CAP_S=900;;
swap) O=$D/out-ho$L-4; CAP_S=150;;
*) echo "the third argument is swap or nothing"; exit 2;;
esac
rm -rf "$O"; mkdir -p "$O"
pkill -f "[s]erial_capture.py $PP"; pkill -f "[s]erial_capture.py $QP"
$PY "$SC" "$PP" $CAP_S "$O/proxy.txt" --ms > /dev/null 2>&1 & C1=$!
$PY "$SC" "$QP" $CAP_S "$O/peri.txt" --ms > /dev/null 2>&1 & C2=$!
trap 'kill $C1 $C2 2>/dev/null; [ -n "$OWNER" ] && { kill -9 $OWNER; kill -CONT $OWNER; } 2>/dev/null' EXIT
sleep 3
FAIL=0
own() { # own CASE: start the owner and wait until it holds the link
$PY "$D/ha.py" "$H" "$KEY" owner > "$O/owner-$1.log" 2>&1 & OWNER=$!
for _ in $(seq 60); do grep -q "OWNER HOLDS LINK" "$O/owner-$1.log" && break; sleep 1; done
grep -q "OWNER HOLDS LINK" "$O/owner-$1.log" || { echo "FAIL: case $1: owner never connected"; FAIL=1; kill -9 $OWNER; return 1; }
ADDR=$(grep -oE "peripheral 0x[0-9a-f]+" "$O/owner-$1.log" | awk '{print $2}')
}
release() { kill -9 $OWNER; kill -CONT $OWNER 2>/dev/null; OWNER=; }
observe() { # observe CASE ARGS...: run the observer, keeping its exit status in obs-CASE.rc
local c=$1; shift
$PY "$D/ha.py" "$H" "$KEY" observe "$@" > "$O/obs-$c.log" 2>&1; echo $? > "$O/obs-$c.rc"
}
if [ "$MODE" = swap ]; then
for r in 1 2 3; do
own "$r" || continue
sleep 5; kill -STOP $OWNER; sleep 4
$PY "$D/ha.py" "$H" "$KEY" swap "$ADDR" > "$O/swap-$r.log" 2>&1
release
echo "round $r: $(grep -o 'CONNECTED on attempt [0-9] at [0-9.]* s' "$O/swap-$r.log" || echo 'never connected')"
grep -q 'CONNECTED on attempt' "$O/swap-$r.log" || FAIL=1
sleep 15
done
[ "$FAIL" = 0 ] && echo PASS || { echo "FAIL: a round never connected"; exit 1; }
exit 0
fi
echo "CASE C $(date +%T)"
own C && { sleep 5; kill -9 $OWNER; OWNER=; sleep 4; observe C 60; }
sleep 10
echo "CASE H $(date +%T)"
own H && { sleep 5; kill -STOP $OWNER; sleep 4; observe H 300 connect "$ADDR"; release; }
sleep 10
echo "CASE N $(date +%T)"
own N && { sleep 5; kill -STOP $OWNER; sleep 200; observe N 40; release; }
for c in C H N; do
f=$O/obs-$c.log; [ -s "$f" ] || { echo "$c: no observer run"; FAIL=1; continue; }
rc=$(cat "$O/obs-$c.rc"); first=$(grep -c 'FIRST ADVERT' "$f")
echo "$c: observer exit $rc, first advert $first, last count '$(grep 'adverts so far' "$f" | tail -1 | sed 's/.*so far //')'," \
"$(grep -o 'state connected=[A-Za-z]*.*after [0-9.]* s' "$f" | head -1)"
[ "$rc" = 0 ] && [ "$first" -gt 0 ] || FAIL=1
done
R=$(grep -a -c -E 'Guru|abort\(\)|Backtrace|rst:0x' "$O/proxy.txt")
echo "proxy: replaces warnings $(grep -a -c replaces "$O/proxy.txt"), resets $R"
[ "$R" = 0 ] || FAIL=1
[ "$FAIL" = 0 ] && echo PASS || { echo "FAIL: an observer failed or never saw the peripheral advertise, or the proxy reset"; exit 1; }
.agents/skills/hardware-test/scripts/bluetooth_proxy_half_open/ha.py
+157
View File
@@ -0,0 +1,157 @@
"""Play Home Assistant against a bluetooth_proxy.
usage: ha.py HOST KEY owner connect to the test peripheral through the proxy, then idle forever
ha.py HOST KEY swap ADDR connect at once after subscribing, retry on the first advert, release
ha.py HOST KEY observe SECONDS [connect ADDR]
watch the peripheral's adverts and the proxy's slot report; optionally
ask the proxy to connect to ADDR at the end and then release it
KEY of - is a plaintext API. The peripheral is found by its manufacturer data (FF FF 21 56, see peripheral.yaml).
"""
import asyncio
import sys
import time
from aioesphomeapi import APIClient, APIConnectionError
HOST, KEY, ROLE = sys.argv[1], sys.argv[2], sys.argv[3]
MARK = b"\xff\xff\x21\x56"
def log(*a: object) -> None:
print(f"{time.time():.3f} {ROLE}", *a, flush=True)
async def find_peripheral(c: APIClient) -> tuple[int, int]:
fut = asyncio.get_running_loop().create_future()
def on_adv(resp) -> None:
for adv in resp.advertisements:
if MARK in adv.data and not fut.done():
fut.set_result((adv.address, adv.address_type))
# Stay subscribed like Home Assistant does: with no subscriber the proxy releases every link
c.subscribe_bluetooth_le_raw_advertisements(on_adv)
return await asyncio.wait_for(fut, 60)
async def owner(c: APIClient, flags: int) -> None:
addr, atype = await find_peripheral(c)
log(f"peripheral {addr:#x} seen, connecting")
if not await connect_once(c, addr, flags, "owner", time.time(), atype):
sys.exit("owner could not connect")
log("OWNER HOLDS LINK")
await asyncio.sleep(10**6)
async def connect_once(
c: APIClient, addr: int, flags: int, label: str, t0: float, atype: int = 0
) -> bool:
st = asyncio.get_running_loop().create_future()
def on_state(connected: bool, mtu: int, err: int) -> None:
log(
f"{label} state connected={connected} mtu={mtu} err={err} at {time.time() - t0:.2f} s"
)
if not st.done():
st.set_result(connected)
log(f"{label} connect at {time.time() - t0:.2f} s")
try:
await c.bluetooth_device_connect(
addr, on_state, timeout=30, feature_flags=flags, address_type=atype
)
return await asyncio.wait_for(st, 30)
except (TimeoutError, APIConnectionError) as e:
# TimeoutAPIError and a dropped API link are both APIConnectionError; anything else is a rig bug
log(f"{label} error {e!r} at {time.time() - t0:.2f} s")
return False
async def swap(c: APIClient, flags: int, addr: int) -> None:
t0 = time.time()
adv = asyncio.Event()
def on_adv(resp) -> None:
for a in resp.advertisements:
if MARK in a.data and not adv.is_set():
log(f"FIRST ADVERT after {time.time() - t0:.2f} s")
adv.set()
c.subscribe_bluetooth_le_raw_advertisements(on_adv)
for attempt in (1, 2):
if attempt == 2:
await asyncio.wait_for(adv.wait(), 60)
if await connect_once(c, addr, flags, f"attempt {attempt}", t0):
log(f"CONNECTED on attempt {attempt} at {time.time() - t0:.2f} s")
break
else:
log("both attempts failed, nothing to release")
return
await c.bluetooth_device_disconnect(addr)
await asyncio.sleep(2)
async def observe(
c: APIClient, flags: int, secs: float, connect_addr: int | None
) -> None:
seen = {"n": 0, "first": None}
def on_adv(resp) -> None:
for adv in resp.advertisements:
if MARK in adv.data:
seen["n"] += 1
if seen["first"] is None:
seen["first"] = time.time()
log("FIRST ADVERT from peripheral")
c.subscribe_bluetooth_le_raw_advertisements(on_adv)
end = time.time() + secs
while time.time() < end:
await asyncio.sleep(10)
log(f"adverts so far {seen['n']}")
if connect_addr is None:
return
log(f"asking proxy to connect {connect_addr:#x}")
ok = await connect_once(c, connect_addr, flags, "observer", time.time())
await c.bluetooth_device_disconnect(connect_addr)
log("released")
n0 = seen["n"]
await asyncio.sleep(20)
log(f"adverts in 20 s after release {seen['n'] - n0}")
if not ok:
sys.exit("observer connect failed")
async def main() -> None:
c = APIClient(
HOST,
6053,
None,
noise_psk=None if KEY == "-" else KEY,
client_info="Home Assistant test",
)
await c.connect(login=True)
info = await c.device_info()
flags = info.bluetooth_proxy_feature_flags_compat(c.api_version)
log("api connected")
c.subscribe_bluetooth_connections_free(
lambda free, limit, alloc: log(
f"slots free={free}/{limit} allocated={[hex(a) for a in alloc]}"
)
)
if ROLE == "owner":
await owner(c, flags)
elif ROLE == "swap":
await swap(c, flags, int(sys.argv[4], 16))
else:
addr = (
int(sys.argv[6], 16)
if len(sys.argv) > 6 and sys.argv[5] == "connect"
else None
)
await observe(c, flags, float(sys.argv[4]), addr)
await c.disconnect()
asyncio.run(main())
.agents/skills/hardware-test/scripts/bluetooth_proxy_half_open/peripheral.yaml
+38
View File
@@ -0,0 +1,38 @@
# Single client BLE peripheral: advertises only while nobody is connected.
esphome:
name: btperi
esp32:
board: esp32-s3-devkitc-1
variant: esp32s3
flash_size: 8MB
framework:
type: esp-idf
logger:
level: DEBUG
baud_rate: 115200
hardware_uart: UART0
esp32_ble:
name: btperi
esp32_ble_server:
manufacturer_data: [0xFF, 0xFF, 0x21, 0x56]
on_connect:
- logger.log: {format: "PERI connected", level: INFO}
on_disconnect:
- logger.log: {format: "PERI disconnected", level: INFO}
services:
- uuid: 2a7b0000-0000-1000-8000-00805f9b34fb
advertise: true
characteristics:
- uuid: 2a7b0001-0000-1000-8000-00805f9b34fb
read: true
notify: true
value: "hello"
interval:
- interval: 30s
then:
- logger.log: {format: "PERI alive", level: INFO}
.agents/skills/hardware-test/scripts/bluetooth_proxy_half_open/proxy.yaml
+38
View File
@@ -0,0 +1,38 @@
# bluetooth_proxy under test: VERBOSE with the busy tags at DEBUG, logs on UART0.
substitutions:
name: btprox
esphome:
name: ${name}
esp32:
board: esp32dev
framework:
type: esp-idf
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
power_save_mode: none
api:
encryption:
key: !secret api_key
reboot_timeout: 0s
logger:
level: VERBOSE
logs:
esp32_ble_tracker: DEBUG
esp32_ble: DEBUG
api.service: DEBUG
scheduler: DEBUG
component: DEBUG
wifi: DEBUG
esp32_ble_tracker:
scan_parameters:
active: true
bluetooth_proxy:
active: true
.agents/skills/hardware-test/scripts/crash_report/crash-common.yaml
+26
View File
@@ -0,0 +1,26 @@
# Crash buttons for the crash report flow (#21596, #22288). A package: the per-run file supplies the board and name.
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
api:
reboot_timeout: 0s
ota:
- platform: esphome
logger:
level: DEBUG
button:
- platform: template
name: crash abort
on_press:
- lambda: abort();
- platform: template
name: crash null store
on_press:
- lambda: '*(volatile uint32_t *) nullptr = 1;'
- platform: template
name: crash div zero
on_press:
- lambda: |-
volatile int z = 0;
volatile int r = 10 / z;
ESP_LOGI("hwt", "r=%d", r);
.agents/skills/hardware-test/scripts/crash_report/drive.py
+106
View File
@@ -0,0 +1,106 @@
"""Press a crash button, reconnect, fetch the crash report twice; print capabilities around it and the replayed log.
usage: drive.py HOST BUTTON_OBJECT_ID env: API_KEY (unset for a plaintext API)
An earlier report is read first so it cannot pass for this crash. Exits 1 when the device still answers after the
press, does not offer a crash report after the crash, or the report has no reason or a PC of 0.
"""
import asyncio
import pathlib
import re
import sys
import time
from aioesphomeapi import APIClient, ButtonInfo
from aioesphomeapi.model import CrashReason, LogLevel
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
import apiconn # noqa: E402
HOST, BTN = sys.argv[1], sys.argv[2]
T0 = time.monotonic()
def mark(w: str) -> None:
print(f"{time.monotonic() - T0:7.2f} {w}", flush=True)
async def connect() -> APIClient:
return await apiconn.connect(HOST, tries=90)
async def main() -> str | None:
"""Run the flow; returns why it failed, or None."""
c = await connect()
before = (await c.device_capabilities()).crash_report
mark(f"before: crash_report={before}")
if before:
# reading it drops the record at the next reboot, so only a new crash leaves one
old = await c.crash_report()
mark(f"read the earlier report first: reason={old.reason}")
ents, _ = await c.list_entities_services()
key = next((e.key for e in ents if e.object_id == BTN), None)
if key is None:
await c.disconnect()
buttons = [e.object_id for e in ents if isinstance(e, ButtonInfo)]
return f"no button {BTN!r}, the device has {buttons}"
mark(f"PRESS {BTN}")
c.button_command(key)
await asyncio.sleep(2)
try:
await asyncio.wait_for(c.device_info(), 3)
except Exception: # noqa: BLE001
mark("no answer after the press (expected)")
else:
await c.disconnect()
return (
"the device still answers after the press, so the button did not crash it"
)
try:
await c.disconnect()
except Exception: # noqa: BLE001
mark("disconnect after the crash failed (expected)")
await asyncio.sleep(3)
c = await connect()
mark("reconnected")
offered = (await c.device_capabilities()).crash_report
mark(f"after crash: crash_report={offered}")
r = await c.crash_report()
mark(
f"REPORT1 flags={r.flags!r} reason={r.reason} pc={r.pc:#010x} cause={r.cause} "
f"fault={r.fault_address:#010x} build_time={r.build_time} crashed_core={r.crashed_core}"
)
for core in r.cores:
mark(f" core {core.core}: " + " ".join(f"{a:#010x}" for a in core.backtrace))
r2 = await c.crash_report()
mark(f"REPORT2 flags={r2.flags!r} reason={r2.reason} cores={len(r2.cores)}")
mark(f"after read: crash_report={(await c.device_capabilities()).crash_report}")
lines: list[str] = []
c.subscribe_logs(
lambda m: lines.append(apiconn.log_text(m)),
log_level=LogLevel.LOG_LEVEL_VERY_VERBOSE,
dump_config=True,
)
await asyncio.sleep(4)
for line in lines:
if re.search(
r"crash|Crash|CRASH|PC|BT\d|backtrace|Backtrace|reset reason|Reset", line
):
mark("LOG " + line[:160])
await c.disconnect()
c = await connect()
mark(f"second client: crash_report={(await c.device_capabilities()).crash_report}")
r3 = await c.crash_report()
mark(f"REPORT3 flags={r3.flags!r}")
await c.disconnect()
if not offered:
return "no crash report offered after the crash"
if r.reason in (None, CrashReason.UNKNOWN) or r.pc == 0:
return f"the report has reason {r.reason} and PC {r.pc:#010x}"
return None
if err := asyncio.run(main()):
print(f"FAIL: {err}")
sys.exit(1)
print("PASS")
.agents/skills/hardware-test/scripts/crash_report/peek.py
+35
View File
@@ -0,0 +1,35 @@
"""Print the crash report capability and how many replayed 'CRASH DETECTED' lines a new log client gets.
usage: peek.py HOST env: API_KEY (unset for a plaintext API). Press a crash button with api_button.py.
"""
import asyncio
import pathlib
import sys
from aioesphomeapi.model import LogLevel
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from apiconn import connect, log_text # noqa: E402
async def main() -> None:
c = await connect(sys.argv[1], tries=60)
caps = await c.device_capabilities()
lines: list[str] = []
c.subscribe_logs(
lambda m: lines.append(log_text(m)),
log_level=LogLevel.LOG_LEVEL_DEBUG,
dump_config=True,
)
await asyncio.sleep(4)
print(
"caps",
caps.crash_report,
"replay lines",
sum("CRASH DETECTED" in line for line in lines),
)
await c.disconnect()
asyncio.run(main())
.agents/skills/hardware-test/scripts/ds248x_sim/drive.py
+297
View File
@@ -0,0 +1,297 @@
"""Run the ds248x fault phases against the DS2482-800 simulator and summarise them.
usage: SC=path/to/serial_capture.py drive.py TAG SIM_PORT DUT_PORT [PHASES]
PHASES is a comma list of c, cd, z, b, k, dead (default c,z,b,k,dead). Holds the simulator port for the whole run
(log and commands); the DUT log is captured per phase into TAG-<phase>.log, each phase starting with a DUT reset.
Exits 1 when the simulator never reports, the simulator port fails, the DUT capture fails, a phase ends without a
fresh simulator report, a sensor got no correct reading after the last fault of the phase had SETTLE seconds to clear
(the recovery window), the DUT logged a CRC, held low, busy timeout or no response line in the recovery window, any
temperature is wrong, a phase other than dead logged a failed recovery, a failed hub or a component marked failed, a
ds248x warning was still set at the end of a phase, a fault phase moved its injection counter (counted when the
DUT meets the fault) by other than the number of faults sent (arm_lost counts arms merged into a pending one) or,
for a NACK fault, never moved the nacked counter, a write delivered
data while a NACK was armed (nack_miss, including a write followed by a repeated start into a read), the DUT sent an address-only write (empty_wr, which would make
nacked ambiguous), a write was cut off by a repeated start into another write and never processed
(dropped), a fault is still pending at the end of a phase, the simulator counted a config write with a wrong complement (cfg_bad) or an unknown
command or argument (bad_cmd), a counter is missing from the simulator CNT line, the simulator aborted a read reply
(tx_abrt, not gated in the dead phase), a phase that does not reset the chip (all but b and k) counted a ROM match on
the wrong channel (wrong_ch) or a 1-Wire command without the active pull-up bit (ops_no_apu), the simulator never
confirmed going dead, or the DUT log shows no sign of the dead hub (no response, warning, failed hub or failed
component) in the dead phase. DUT capture stderr goes to TAG-<phase>.err. The whole phase CRC, held low, busy
timeout and no response counts are printed for information only: the faults cause them.
"""
import os
import pathlib
import re
import subprocess
import sys
import threading
import time
import serial
TAG, SIM, DUT = sys.argv[1:4]
PHASES = sys.argv[4].split(",") if len(sys.argv) > 4 else ["c", "z", "b", "k", "dead"]
CAP = [sys.executable, os.environ["SC"]]
# seconds after the last fault action before the recovery window opens
SETTLE = 3.0
STAMP = re.compile(r"^\[(\d\d):(\d\d):(\d\d)(?:\.(\d{3}))?\]")
# every sensor dspd.yaml configures, with the temperature the simulator serves
EXPECT = {"t0": 21.5, "t1": 33.0, "t2a": -5.25, "t2b": 40.0}
ANSI = re.compile(r"\x1b\[[0-9;]*m")
COUNTERS = (
"wrong_ch",
"nacked",
"nack_miss",
"empty_wr",
"dropped",
"arm_lost",
"drst",
"ops_no_apu",
"inj_c",
"inj_z",
"inj_b",
"inj_k",
"readsp",
"cfg_bad",
"bad_cmd",
"tx_abrt",
)
sim = serial.Serial(SIM, 115200, timeout=0.2)
sim_lines: list[tuple[float, str]] = []
stop = threading.Event()
failed: list[str] = []
reader_error: list[BaseException] = []
def sim_reader() -> None:
buf = bytearray()
while not stop.is_set():
try:
buf += sim.read(4096)
except Exception as err: # noqa: BLE001 - reported by main() and per phase
reader_error.append(err)
print(f"FAIL: simulator port read failed: {err!r}", flush=True)
return
*lines, rest = buf.split(b"\n")
buf = bytearray(rest)
now = time.time()
sim_lines.extend(
(now, ANSI.sub("", line.decode(errors="replace")).strip()) for line in lines
)
def send(c: str) -> None:
sim.write(c.encode())
sim.flush()
def last_cnt(before: float) -> dict[str, int]:
for t, line in reversed(sim_lines):
if t <= before and "CNT " in line:
body = line.split("CNT ", 1)[1]
return {k: int(v) for k, v in re.findall(r"(\w+)=(-?\d+)", body)}
return {}
def after(log: str, when: float) -> str:
"""Lines of a serial_capture --ms log stamped after the wall clock time `when`."""
lt = time.localtime(when)
ref = lt.tm_hour * 3600 + lt.tm_min * 60 + lt.tm_sec + when % 1
keep = []
for line in log.splitlines():
if m := STAMP.match(line):
sod = int(m[1]) * 3600 + int(m[2]) * 60 + int(m[3]) + int(m[4] or 0) / 1000
if 0 < (sod - ref) % 86400 < 43200: # survives midnight
keep.append(line)
return "\n".join(keep)
def phase(
name: str, seconds: int, actions: list[tuple[float, str]], pre: str = ""
) -> None:
if pre:
n_pre = len(sim_lines)
send(pre)
time.sleep(0.3)
if want := CONFIRMED_BY.get(pre):
deadline = time.time() + 3
while not any(line.endswith(want) for _, line in sim_lines[n_pre:]):
if time.time() > deadline:
failed.append(
f"{name} (simulator never logged {want} after {pre!r})"
)
break
time.sleep(0.05)
out = pathlib.Path(f"{TAG}-{name}.log")
out.unlink(missing_ok=True)
with pathlib.Path(f"{TAG}-{name}.err").open("wb") as err:
p = subprocess.Popen(
[*CAP, DUT, str(seconds), str(out), "--reset", "--ms"],
stdout=subprocess.DEVNULL,
stderr=err,
)
t0 = last_fault = time.time()
for at, c in actions:
time.sleep(max(0.0, t0 + at - time.time()))
send(c)
last_fault = time.time()
if rc := p.wait():
failed.append(f"{name} (DUT capture exited {rc}, see {TAG}-{name}.err)")
n0 = len(sim_lines)
send("s") # one more simulator report
deadline = time.time() + 6
while time.time() < deadline and not any(
"CNT " in line for _, line in sim_lines[n0:]
):
time.sleep(0.05)
fresh = any("CNT " in line for _, line in sim_lines[n0:])
a, b = last_cnt(t0), last_cnt(time.time())
if missing := [k for k in (*COUNTERS, "pend") if k not in a or k not in b]:
failed.append(f"{name} (missing counters {missing} on the simulator CNT line)")
delta = {k: b.get(k, 0) - a.get(k, 0) for k in COUNTERS}
log = out.read_text(encoding="utf-8", errors="replace") if out.exists() else ""
temps = re.findall(r"'(\w+)': Got Temperature=(-?[\d.]+)", log)
per = dict.fromkeys(EXPECT, 0)
wrong = []
for s, v in temps:
per[s] = per.get(s, 0) + 1
if abs(float(v) - EXPECT.get(s, 999)) > 0.01:
wrong.append(f"{s}={v}")
def errors(text: str) -> dict[str, int]:
return {
"crc": len(re.findall(r"[Cc]hecksum|CRC", text)),
"held_low": text.count("held low"),
"busy_to": text.count("busy timeout"),
"no_resp": text.count("did not respond"),
}
counts = errors(log) | {
"recov_fail": log.count("recovery failed"),
"marked_failed": len(re.findall(r"was marked as failed", log)),
"warn_set": len(re.findall(r"ds248x set Warning", log)),
"warn_clear": len(re.findall(r"ds248x cleared Warning", log)),
"hub_failed_bus": log.count("DS248x hub failed"),
}
# the recovery window: from SETTLE seconds after the last fault action to the end of the capture
tail = after(log, last_fault + SETTLE)
late_ok = dict.fromkeys(EXPECT, 0)
for s, v in re.findall(r"'(\w+)': Got Temperature=(-?[\d.]+)", tail):
if s in EXPECT and abs(float(v) - EXPECT[s]) <= 0.01:
late_ok[s] += 1
late_err = {k: n for k, n in errors(tail).items() if n}
more = "..." if len(wrong) > 6 else ""
print(
f"{TAG} {name}: readings={per} recovered={late_ok} wrong={wrong[:6]}{more} n_wrong={len(wrong)} {counts} "
f"late_errors={late_err} sim={delta}",
flush=True,
)
if silent := [s for s, n in late_ok.items() if not n]:
failed.append(
f"{name} (no correct reading from {silent} in the recovery window)"
)
if late_err:
failed.append(f"{name} (errors in the recovery window {late_err})")
if name not in DUT_SAW and (
hard := {
k: counts[k]
for k in ("recov_fail", "marked_failed", "hub_failed_bus")
if counts[k]
}
):
failed.append(f"{name} (failed recovery, hub or component {hard})")
warn = re.findall(r"ds248x (set|cleared) Warning", log)
if warn and warn[-1] == "set":
failed.append(f"{name} (ds248x warning still set at the end of the phase)")
if wrong:
failed.append(f"{name} ({len(wrong)} wrong temperatures)")
if (inj := INJECTED_BY.get(name)) and delta[inj] != (
sent := sum(c == inj[-1] for _, c in actions)
):
failed.append(
f"{name} ({inj} moved {delta[inj]} for {sent} faults sent, arm_lost={delta['arm_lost']})"
)
if name in NACK_PHASES and not delta["nacked"]:
failed.append(f"{name} (nacked never moved, the DUT never got the NACK)")
if name in DUT_SAW and not any(counts[k] for k in DUT_SAW[name]):
failed.append(
f"{name} (no {'/'.join(DUT_SAW[name])} in the DUT log, the DUT never saw the fault)"
)
if delta["nack_miss"]:
failed.append(
f"{name} ({delta['nack_miss']} writes delivered data while a NACK was armed)"
)
if delta["empty_wr"]:
failed.append(
f"{name} ({delta['empty_wr']} address-only writes, nacked cannot tell them from NACKs)"
)
if delta["dropped"]:
failed.append(
f"{name} ({delta['dropped']} writes cut off by a repeated start, never processed)"
)
if malformed := {k: delta[k] for k in ("cfg_bad", "bad_cmd") if delta[k]}:
failed.append(f"{name} (malformed writes {malformed})")
if name not in RESET_PHASES and (
stale := {k: delta[k] for k in ("wrong_ch", "ops_no_apu") if delta[k]}
):
failed.append(f"{name} (stale channel or lost active pull-up {stale})")
if name not in ABORT_OK_PHASES and delta["tx_abrt"]:
failed.append(f"{name} (simulator aborted {delta['tx_abrt']} read replies)")
if b.get("pend"):
failed.append(f"{name} (a fault was still pending at the end of the phase)")
if not fresh or not a or reader_error:
print(f"{TAG} {name}: no fresh simulator report, sim counters are not valid")
failed.append(f"{name} (no simulator report)")
# fault phase -> simulator counter that must move during it
INJECTED_BY = {"c": "inj_c", "cd": "inj_c", "z": "inj_z", "b": "inj_b", "k": "inj_k"}
# fault phases whose fault is a NACK
NACK_PHASES = {"c", "cd", "z", "k"}
# fault phases that reset the chip (channel 0, config cleared) under the driver; the 1-Wire commands left in the
# interrupted transaction may then run on the wrong channel or without APU, so wrong_ch and ops_no_apu are not gated
RESET_PHASES = {"b", "k"}
# phases that switch the controller off, which may abort a read reply in flight
ABORT_OK_PHASES = {"dead"}
# phase -> DUT log counts of which at least one must be non-zero
DUT_SAW = {"dead": ("no_resp", "warn_set", "hub_failed_bus", "marked_failed")}
# pre command -> simulator log line that confirms it took effect
CONFIRMED_BY = {"x": "DEAD"}
# name: (seconds, actions, pre)
RUNS: dict[str, tuple[int, list[tuple[float, str]], str]] = {
"c": (90, [(12 + 6 * i, "c") for i in range(12)], ""),
"cd": (100, [(10 + 3 * i, "c") for i in range(28)], ""),
"z": (50, [(12 + 5 * i, "z") for i in range(6)], ""),
"b": (40, [(12, "b")], ""),
"k": (40, [(12, "k")], ""),
"dead": (45, [(25, "X")], "x"),
}
def main() -> int:
threading.Thread(target=sim_reader, daemon=True).start()
deadline = time.time() + 15
while not any("CNT " in line for _, line in sim_lines):
if time.time() > deadline:
print(
"FAIL: no CNT line from the simulator in 15 s (flashed dssim.yaml? SIM_PORT right?)"
)
return 1
time.sleep(0.2)
for name in PHASES:
phase(name, *RUNS[name])
send("X")
stop.set()
if failed:
print(f"FAIL: {failed}")
return 1
print("PASS")
return 0
if __name__ == "__main__":
sys.exit(main())
Loaded 100 of 3585 files, more files were not shown because too many files have changed in this diff. Show more