给小智加 MCP 灯工具：参数、去重、错误与数字回读

python tools/verify_overlay.py
python tools/project.py configure
python tools/project.py build
python tools/project.py manifest

python tools/project.py flash --port /dev/cu.YOUR_BRIDGE_PORT
python tools/project.py monitor --port /dev/cu.YOUR_BRIDGE_PORT

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"self.lab_led.set","arguments":{"power":true,"request_id":100}}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"self.lab_led.get_state","arguments":{}}}

clang++ -std=c++17 -Wall -Wextra -Werror -fsanitize=address,undefined tests/policy.cpp -o /tmp/a08-policy
/tmp/a08-policy
clang++ -std=c++17 -Wall -Wextra -Werror -fsanitize=address,undefined -Itests/gpio-stubs tests/gpio.cpp -o /tmp/a08-gpio
/tmp/a08-gpio
python3 tests/run_mcp_host.py --output /tmp/a08-mcp-UNUSED-DIRECTORY

// ---- firmware/main/boards/bread-compact-wifi/audited_led_policy.h ----
// SPDX-License-Identifier: MIT
#pragma once
#include <array>
#include <cstddef>
#include <cstdint>
namespace a08 {
enum class Result { APPLIED, DUPLICATE, CONFLICT, FAULT };
struct Snapshot {
    uint32_t boot_id;
    bool fault, last_confirmed_power, pad_known, pad_level, has_last_request;
    uint32_t last_request;
};
// Single owner: Xiaozhi Application main-task scheduled callbacks only.
// Io implements initialize(), write(bool), read(bool&); all return success.
template <class Io>
class LedPolicy {
public:
    LedPolicy(Io& io, uint32_t boot_id) : io_(io), boot_id_(boot_id) {
        initialized_ = io_.initialize();
        if (!initialized_ || !io_.write(false) || !sample() || pad_)
            latch_fault();
    }
    Result set(uint32_t request_id, bool power) {
        if (!verify())
            return Result::FAULT;
        for (const auto& entry : history_) {
            if (entry.used && entry.id == request_id)
                return entry.power == power ? Result::DUPLICATE : Result::CONFLICT;
        }
        if (!io_.write(power) || !sample() || pad_ != power) {
            latch_fault();
            return Result::FAULT;
        }
        confirmed_ = power;
        last_id_ = request_id;
        has_last_ = true;
        history_[next_] = {true, request_id, power};
        next_ = (next_ + 1) % history_.size();
        return Result::APPLIED;
    }
    Snapshot snapshot() {
        if (!fault_)
            verify();
        else
            sample();
        return {boot_id_, fault_, confirmed_, known_, pad_, has_last_, last_id_};
    }

private:
    struct Entry {
        bool used = false;
        uint32_t id = 0;
        bool power = false;
    };
    bool sample() {
        bool level = false;
        known_ = initialized_ && io_.read(level);
        if (known_)
            pad_ = level;
        return known_;
    }
    bool verify() {
        if (fault_)
            return false;
        if (!sample() || pad_ != confirmed_) {
            latch_fault();
            return false;
        }
        return true;
    }
    void latch_fault() {
        fault_ = true;
        known_ = false;
        // Best effort, not a claim that the pin or the optical LED became low/off.
        if (initialized_ && io_.write(false))
            sample();
    }
    Io& io_;
    uint32_t boot_id_, last_id_ = 0;
    bool initialized_ = false, fault_ = false, confirmed_ = false, known_ = false, pad_ = false,
         has_last_ = false;
    std::array<Entry, 16> history_{};
    std::size_t next_ = 0;
};
}  // namespace a08

// ---- firmware/main/boards/bread-compact-wifi/audited_led_gpio.h ----
// SPDX-License-Identifier: MIT
#pragma once
#include <driver/gpio.h>
namespace a08 {
class GpioLed {
public:
    explicit GpioLed(gpio_num_t pin) : pin_(pin) {}
    bool initialize() {
        // Preload output latch low before enabling the output. INPUT_OUTPUT keeps
        // the input buffer enabled for digital pad feedback; this is not optics.
        if (gpio_set_level(pin_, 0) != ESP_OK)
            return false;
        gpio_config_t c = {};
        c.pin_bit_mask = 1ULL << pin_;
        c.mode = GPIO_MODE_INPUT_OUTPUT;
        c.pull_up_en = GPIO_PULLUP_DISABLE;
        c.pull_down_en = GPIO_PULLDOWN_DISABLE;
        c.intr_type = GPIO_INTR_DISABLE;
        configured_ = gpio_config(&c) == ESP_OK;
        return configured_;
    }
    bool write(bool on) { return configured_ && gpio_set_level(pin_, on ? 1 : 0) == ESP_OK; }
    bool read(bool& level) {
        if (!configured_)
            return false;
        level = gpio_get_level(pin_) != 0;
        return true;
    }

private:
    gpio_num_t pin_;
    bool configured_ = false;
};
}  // namespace a08

// ---- firmware/main/boards/bread-compact-wifi/audited_led_wire.h ----
// SPDX-License-Identifier: MIT
#pragma once
#include <cJSON.h>
#include <cmath>
#include <cstring>
namespace a08 {
inline bool own_tool(const char* name) {
    return std::strcmp(name, "self.lab_led.set") == 0 ||
           std::strcmp(name, "self.lab_led.get_state") == 0;
}
// Called before the fixed upstream PropertyList decoder discards unknown keys
// and converts JSON numbers to int. This is a parsed-arguments contract, not an
// authentication layer, general JSON parser, or a replacement for cJSON.
inline const char* validate_arguments(const char* name, const cJSON* args) {
    const bool set = std::strcmp(name, "self.lab_led.set") == 0;
    if (!args)
        return set ? "A08 arguments required" : nullptr;
    if (!cJSON_IsObject(args))
        return "A08 arguments must be object";
    bool power_seen = false, id_seen = false;
    unsigned count = 0;
    for (const cJSON* p = args->child; p; p = p->next) {
        if (++count > 2 || !p->string)
            return "A08 too many arguments";
        if (!set)
            return "A08 query takes no arguments";
        if (std::strcmp(p->string, "power") == 0) {
            if (power_seen || !cJSON_IsBool(p))
                return "A08 power must be one boolean";
            power_seen = true;
        } else if (std::strcmp(p->string, "request_id") == 0) {
            if (id_seen || !cJSON_IsNumber(p) || !std::isfinite(p->valuedouble) ||
                p->valuedouble < 0 || p->valuedouble > 2147483647.0 ||
                p->valuedouble != static_cast<double>(p->valueint))
                return "A08 request_id must be one integer in range";
            id_seen = true;
        } else
            return "A08 unknown argument";
    }
    if (set && (!power_seen || !id_seen))
        return "A08 missing argument";
    char* canonical = cJSON_PrintUnformatted(args);
    if (!canonical)
        return "A08 serialization allocation failed";
    const size_t bytes = std::strlen(canonical);
    cJSON_free(canonical);
    if (bytes > 64)
        return "A08 canonical arguments exceed64 bytes";
    return nullptr;
}
}  // namespace a08

// ---- firmware/main/boards/bread-compact-wifi/audited_led_mcp.h ----
// SPDX-License-Identifier: MIT
#pragma once
#include <esp_log.h>
#include "audited_led_policy.h"
#include "audited_led_wire.h"
#include "mcp_server.h"
namespace a08 {
inline cJSON* snapshot_json(const Snapshot& s) {
    cJSON* j = cJSON_CreateObject();
    if (!j)
        throw std::runtime_error("A08 allocation failed");
    cJSON_AddNumberToObject(j, "boot_id", s.boot_id);
    cJSON_AddBoolToObject(j, "fault", s.fault);
    cJSON_AddBoolToObject(j, "last_confirmed_power", s.last_confirmed_power);
    if (s.pad_known)
        cJSON_AddBoolToObject(j, "digital_pad_level", s.pad_level);
    else
        cJSON_AddNullToObject(j, "digital_pad_level");
    if (s.has_last_request)
        cJSON_AddNumberToObject(j, "last_applied_request_id", s.last_request);
    else
        cJSON_AddNullToObject(j, "last_applied_request_id");
    cJSON_AddStringToObject(j, "feedback", "digital_gpio_only_not_optical");
    cJSON_AddNumberToObject(j, "dedup_entries", 16);
    return j;
}
template <class Io>
void register_tools(McpServer& server, LedPolicy<Io>& policy) {
    auto* set_tool = new McpTool(
        "self.lab_led.set",
        "Set only the external laboratory LED. power is boolean. request_id is an integer "
        "0..2147483647. Use a new id for a new command; retry with the same id and power. Cache "
        "holds last16 successful ids for this boot only. Never use this example for a safety "
        "actuator.",
        PropertyList({Property("power", kPropertyTypeBoolean),
                      Property("request_id", kPropertyTypeInteger, 0, 2147483647)}),
        [&policy](const PropertyList& args) -> ReturnValue {
            const bool power = args["power"].template value<bool>();
            const auto id = static_cast<uint32_t>(args["request_id"].template value<int>());
            const Result result = policy.set(id, power);
            ESP_LOGI("a08", "SET request=%lu requested=%d outcome=%s",
                     static_cast<unsigned long>(id), power,
                     result == Result::APPLIED     ? "APPLIED"
                     : result == Result::DUPLICATE ? "DUPLICATE"
                     : result == Result::CONFLICT  ? "CONFLICT"
                                                   : "FAULT");
            if (result == Result::CONFLICT)
                throw std::runtime_error("A08 request id conflict");
            if (result == Result::FAULT)
                throw std::runtime_error("A08 GPIO fault; repair and RESET");
            const Snapshot state = policy.snapshot();
            ESP_LOGI("a08", "PAD boot=%lu confirmed=%d known=%d value=%d fault=%d",
                     static_cast<unsigned long>(state.boot_id), state.last_confirmed_power,
                     state.pad_known, state.pad_level, state.fault);
            if (state.fault)
                throw std::runtime_error("A08 GPIO fault; repair and RESET");
            cJSON* j = snapshot_json(state);
            cJSON_AddNumberToObject(j, "request_id", id);
            cJSON_AddBoolToObject(j, "requested_power", power);
            cJSON_AddBoolToObject(j, "duplicate", result == Result::DUPLICATE);
            return j;
        });
    set_tool->set_validator(
        [](const cJSON* args) { return validate_arguments("self.lab_led.set", args); });
    server.AddTool(set_tool);
    auto* query_tool = new McpTool(
        "self.lab_led.get_state",
        "Query the laboratory LED digital pad and latched fault. No arguments. Digital feedback "
        "does not prove visible light. A fault needs repair and RESET; a query does not clear it.",
        PropertyList(), [&policy](const PropertyList&) -> ReturnValue {
            const Snapshot state = policy.snapshot();
            ESP_LOGI("a08", "QUERY boot=%lu confirmed=%d known=%d value=%d fault=%d",
                     static_cast<unsigned long>(state.boot_id), state.last_confirmed_power,
                     state.pad_known, state.pad_level, state.fault);
            return snapshot_json(state);
        });
    query_tool->set_validator(
        [](const cJSON* args) { return validate_arguments("self.lab_led.get_state", args); });
    server.AddTool(query_tool);
}
}  // namespace a08

// ---- firmware/main/boards/bread-compact-wifi/compact_wifi_board.cc ----
#include <esp_random.h>
#include "application.h"
#include "assets/lang_config.h"
#include "audited_led_gpio.h"
#include "audited_led_mcp.h"
#include "button.h"
#include "codecs/no_audio_codec.h"
#include "config.h"
#include "display/oled_display.h"
#include "led/single_led.h"
#include "mcp_server.h"
#include "system_reset.h"
#include "wifi_board.h"

#include <esp_log.h>
#include <driver/i2c_master.h>
#include <esp_lcd_panel_ops.h>
#include <esp_lcd_panel_vendor.h>

#ifdef SH1106
#include <esp_lcd_panel_sh1106.h>
#endif

#define TAG "CompactWifiBoard"

class CompactWifiBoard : public WifiBoard {
private:
    i2c_master_bus_handle_t display_i2c_bus_;
    esp_lcd_panel_io_handle_t panel_io_ = nullptr;
    esp_lcd_panel_handle_t panel_ = nullptr;
    Display* display_ = nullptr;
    Button boot_button_;
    Button touch_button_;
    Button volume_up_button_;
    Button volume_down_button_;

    void InitializeDisplayI2c() {
        i2c_master_bus_config_t bus_config = {
            .i2c_port = (i2c_port_t)0,
            .sda_io_num = DISPLAY_SDA_PIN,
            .scl_io_num = DISPLAY_SCL_PIN,
            .clk_source = I2C_CLK_SRC_DEFAULT,
            .glitch_ignore_cnt = 7,
            .intr_priority = 0,
            .trans_queue_depth = 0,
            .flags = {
                .enable_internal_pullup = 1,
            },
        };
        ESP_ERROR_CHECK(i2c_new_master_bus(&bus_config, &display_i2c_bus_));
    }

    void InitializeSsd1306Display() {
        // SSD1306 config
        esp_lcd_panel_io_i2c_config_t io_config = {
            .dev_addr = 0x3C,
            .on_color_trans_done = nullptr,
            .user_ctx = nullptr,
            .control_phase_bytes = 1,
            .dc_bit_offset = 6,
            .lcd_cmd_bits = 8,
            .lcd_param_bits = 8,
            .flags =
                {
                    .dc_low_on_data = 0,
                    .disable_control_phase = 0,
                },
            .scl_speed_hz = 400 * 1000,
        };

        ESP_ERROR_CHECK(esp_lcd_new_panel_io_i2c(display_i2c_bus_, &io_config, &panel_io_));

        ESP_LOGI(TAG, "Install SSD1306 driver");
        esp_lcd_panel_dev_config_t panel_config = {};
        panel_config.reset_gpio_num = GPIO_NUM_NC;
        panel_config.bits_per_pixel = 1;

        esp_lcd_panel_ssd1306_config_t ssd1306_config = {
            .height = static_cast<uint8_t>(DISPLAY_HEIGHT),
        };
        panel_config.vendor_config = &ssd1306_config;

#ifdef SH1106
        ESP_ERROR_CHECK(esp_lcd_new_panel_sh1106(panel_io_, &panel_config, &panel_));
#else
        ESP_ERROR_CHECK(esp_lcd_new_panel_ssd1306(panel_io_, &panel_config, &panel_));
#endif
        ESP_LOGI(TAG, "SSD1306 driver installed");

        // Reset the display
        ESP_ERROR_CHECK(esp_lcd_panel_reset(panel_));
        if (esp_lcd_panel_init(panel_) != ESP_OK) {
            ESP_LOGE(TAG, "Failed to initialize display");
            display_ = new NoDisplay();
            return;
        }
        ESP_ERROR_CHECK(esp_lcd_panel_invert_color(panel_, false));

        // Set the display to on
        ESP_LOGI(TAG, "Turning display on");
        ESP_ERROR_CHECK(esp_lcd_panel_disp_on_off(panel_, true));

        display_ = new OledDisplay(panel_io_, panel_, DISPLAY_WIDTH, DISPLAY_HEIGHT, DISPLAY_MIRROR_X, DISPLAY_MIRROR_Y);
    }

    void InitializeButtons() {
        boot_button_.OnClick([this]() {
            auto& app = Application::GetInstance();
            if (app.GetDeviceState() == kDeviceStateStarting) {
                EnterWifiConfigMode();
                return;
            }
            app.ToggleChatState();
        });
        touch_button_.OnPressDown([this]() {
            Application::GetInstance().StartListening();
        });
        touch_button_.OnPressUp([this]() {
            Application::GetInstance().StopListening();
        });

        volume_up_button_.OnClick([this]() {
            auto codec = GetAudioCodec();
            auto volume = codec->output_volume() + 10;
            if (volume > 100) {
                volume = 100;
            }
            codec->SetOutputVolume(volume);
            GetDisplay()->ShowNotification(Lang::Strings::VOLUME + std::to_string(volume));
        });

        volume_up_button_.OnLongPress([this]() {
            GetAudioCodec()->SetOutputVolume(100);
            GetDisplay()->ShowNotification(Lang::Strings::MAX_VOLUME);
        });

        volume_down_button_.OnClick([this]() {
            auto codec = GetAudioCodec();
            auto volume = codec->output_volume() - 10;
            if (volume < 0) {
                volume = 0;
            }
            codec->SetOutputVolume(volume);
            GetDisplay()->ShowNotification(Lang::Strings::VOLUME + std::to_string(volume));
        });

        volume_down_button_.OnLongPress([this]() {
            GetAudioCodec()->SetOutputVolume(0);
            GetDisplay()->ShowNotification(Lang::Strings::MUTED);
        });
    }

    // 物联网初始化，逐步迁移到 MCP 协议
    void InitializeTools() {
        static a08::GpioLed led_io(LAMP_GPIO);
        static a08::LedPolicy<a08::GpioLed> led(led_io, esp_random());
        static const bool registered = []() {
            a08::register_tools(McpServer::GetInstance(), led);
            return true;
        }();
        (void)registered;
    }

public:
    CompactWifiBoard() :
        boot_button_(BOOT_BUTTON_GPIO),
        touch_button_(TOUCH_BUTTON_GPIO),
        volume_up_button_(VOLUME_UP_BUTTON_GPIO),
        volume_down_button_(VOLUME_DOWN_BUTTON_GPIO) {
        InitializeDisplayI2c();
        InitializeSsd1306Display();
        InitializeButtons();
        InitializeTools();
    }

    virtual Led* GetLed() override {
        static SingleLed led(BUILTIN_LED_GPIO);
        return &led;
    }

    virtual AudioCodec* GetAudioCodec() override {
#ifdef AUDIO_I2S_METHOD_SIMPLEX
        static NoAudioCodecSimplex audio_codec(AUDIO_INPUT_SAMPLE_RATE, AUDIO_OUTPUT_SAMPLE_RATE,
            AUDIO_I2S_SPK_GPIO_BCLK, AUDIO_I2S_SPK_GPIO_LRCK, AUDIO_I2S_SPK_GPIO_DOUT, AUDIO_I2S_MIC_GPIO_SCK, AUDIO_I2S_MIC_GPIO_WS, AUDIO_I2S_MIC_GPIO_DIN);
#else
        static NoAudioCodecDuplex audio_codec(AUDIO_INPUT_SAMPLE_RATE, AUDIO_OUTPUT_SAMPLE_RATE,
            AUDIO_I2S_GPIO_BCLK, AUDIO_I2S_GPIO_WS, AUDIO_I2S_GPIO_DOUT, AUDIO_I2S_GPIO_DIN);
#endif
        return &audio_codec;
    }

    virtual Display* GetDisplay() override {
        return display_;
    }
};

DECLARE_BOARD(CompactWifiBoard);