Esp32 MCP Server

ESP32 MCP服务器


A. 模型上下文协议 （MCP）服务器在ESP32上运行（Nordic nRF52840在仅传感器模式下运行），通过WebSocket/JSON-RPC 2.0将真实世界的传感器数据和总线协议暴露给AI助手和自动化工具。

将AI代理直接连接到您的硬件：查询I2C传感器，解析NMEA 0183 GPS/海洋数据，解码NMEA 2000和OBD-II CAN帧，重放总线历史记录——所有这些都是通过标准MCP接口完成的。

architecture

______________________________________________________________________

特性

______________________________________________________________________

支持的板

ESP32板——全MCP服务器（WiFi+WebSocket+CAN）

nRF52840板——仅传感器（I2C+串行，无WiFi）

nRF52840目标运行单独的 main_nrf.cpp 入口点：仅传感器+I2C+串行输出。没有WiFi，没有MCP WebSocket，没有LittleFS，没有总线历史记录。对于WiFi上的全MCP，通过连接到UART1的AT命令模式下的ESP32-C3桥接。

电路板特征矩阵

______________________________________________________________________

建筑

flowchart TD
    Client[AI Agent / MCP Client] -->|WebSocket :9000 JSON-RPC 2.0| MCPServer

    subgraph ESP32
        MCPServer -->|resources/list| Resources
        MCPServer -->|sensors/i2c/scan| SensorMgr
        MCPServer -->|sensors/read| SensorMgr
        MCPServer -->|buses/serial/read| BusReader
        MCPServer -->|buses/can/read| BusReader
        MCPServer -->|bus/history/read| BusHistory
        MCPServer -->|bus/history/config/*| BusHistory

        SensorMgr -->|Wire I2C| I2CSensors[BME280 · MPU6050 · ADS1115\nSHT31 · BH1750 · INA219]
        BusReader -->|UART| NMEAParser[NMEA 0183 Parser]
        BusReader -->|CAN TWAI| CANParser[NMEA 2000 / OBD-II Parser]
        BusReader -->|feed| BusHistory[Bus History\nRing Buffers]
        BusHistory --> LittleFS

        NetworkMgr[Network Manager] --> WiFi
        NetworkMgr --> WebSetup[Setup UI :80]
        DiscoveryMgr[Discovery Manager] -->|mDNS + UDP| Network
        Metrics[Metrics System] --> LittleFS
        uLogger --> LittleFS
    end

    MCPServer --> Metrics
    MCPServer --> uLogger

______________________________________________________________________

硬件

引脚分配（ESP32-S3-DevKitC-1）

nRF52840 DK引脚分配

物料清单

ESP32-S3-DevKitC-1接线

                    ┌──────────────────────────────────────┐
                    │         ESP32-S3-DevKitC-1            │
                    │                                       │
             3V3 ───┤ 3V3                          GND ├─── GND
             GND ───┤ GND                          IO0 ├
                    │                                   │
  I2C SDA ── IO8 ───┤ IO8  ┌──────────┐       IO17 ├─── UART1 TX → GPS
  I2C SCL ── IO9 ───┤ IO9  │  ESP32   │       IO16 ├─── UART1 RX ← GPS
                    │ IO10 │    S3    │       IO15 ├
                    │ IO11 └──────────┘       IO14 ├
                    │ IO12                    IO13 ├
                    │ IO3                      IO4 ├─── CAN RX ← TJA1050
                    │ IO46                     IO5 ├─── CAN TX → TJA1050
                    │                               │
                    │    USB (flash / serial log)   │
                    └───────────────────────────────┘

I2C传感器接线

所有传感器共享一条总线。将SDA和SCL的4.7 kΩ上拉电压添加到3V3。

ESP32-S3      BME280       MPU6050      ADS1115      INA219
─────────     ───────      ───────      ───────      ───────
IO8 (SDA)─────SDA──────────SDA──────────SDA──────────SDA
IO9 (SCL)─────SCL──────────SCL──────────SCL──────────SCL
3V3  ──────────VCC──────────VCC──────────VCC──────────VCC
GND  ──────────GND──────────GND──────────GND──────────GND
               SDO→GND      AD0→GND      ADDR→GND
               (0x76)       (0x68)       (0x48)       (0x40)

其他支持的传感器（相同的总线接线）： SHT31 （0x44）， BH1750 （0x23）。

NMEA 0183接线（GPS/海图绘图仪）

GPS / chart plotter              ESP32-S3
───────────────────              ────────
TX  (3.3 V TTL NMEA out) ─────── IO16 (UART1 RX)
RX  (optional NMEA in)   ─────── IO17 (UART1 TX)
GND                      ─────── GND
VCC (3.3 V)              ─────── 3V3

如果设备输出RS-232电平，请使用MAX3232电平转换器。切勿将RS-232直接连接到ESP32 GPIO。

CAN总线接线（NMEA 2000/OBD-II）

TJA1050 / SN65HVD230             ESP32-S3
────────────────────             ────────
CTXD                  ─────────── IO5 (CAN TX)
CRXD                  ─────────── IO4 (CAN RX)
VCC (5 V for TJA1050) ─────────── VIN / external 5 V
GND                   ─────────── GND
CANH ──────────────── NMEA 2000 backbone / OBD-II CANH
CANL ──────────────── NMEA 2000 backbone / OBD-II CANL

NMEA 2000的运行速度为250 kbps。OBD-II以500kbps的速度运行。在您的设备中设置波特率 CANBusReader 相应地配置。

______________________________________________________________________

软件先决条件

• 平台IO核心 CLI或VS代码的PlatformIO IDE插件
• Python 3.8+
• Git

pip install platformio

______________________________________________________________________

构建和Flash

# 1. Clone
git clone https://github.com/navado/ESP32MCPServer.git
cd ESP32MCPServer

# 2. Install library dependencies
pio pkg install

# 3. Upload web assets to LittleFS (optional but recommended)
pio run -t uploadfs -e esp32-s3-devkitc-1

# 4. Build firmware
pio run -e esp32-s3-devkitc-1

# 5. Flash
pio run -t upload -e esp32-s3-devkitc-1

# 6. Monitor
pio device monitor --baud 115200

nRF52840

pio run -e nrf52840-dk
pio run -t upload -e nrf52840-dk

______________________________________________________________________

首次运行

1. 板上的电源。它广播WiFi AP： ESP32_XXXXXX （MAC地址的最后6位十六进制数字）。
2. 连接到该AP并打开 http://192.168.4.1.
3. 输入您的WiFi凭据，然后单击“保存”。
4. 该板加入您的网络，并在串行控制台上打印其IP地址。
5. 将MCP客户端连接到 ws://:9000.

______________________________________________________________________

Web仪表板

基于浏览器的仪表板由flash提供 http:///app.

______________________________________________________________________

HTTP端点（端口80）

______________________________________________________________________

MCP API参考（WebSocket端口9000）

所有方法使用 JSON-RPC 2.0 通过WebSocket。

协议

传感器

sensors/i2c/scan

{"jsonrpc":"2.0","method":"sensors/i2c/scan","id":1}

{
  "jsonrpc":"2.0","id":1,
  "result":{"devices":[
    {"address":118,"name":"BME280","supported":true,"parameters":["temperature","pressure","humidity"]},
    {"address":104,"name":"MPU6050","supported":true,"parameters":["accel_x","accel_y","accel_z","gyro_x","gyro_y","gyro_z","temperature"]}
  ]}
}

sensors/read

{"jsonrpc":"2.0","method":"sensors/read","id":2,"params":{"sensorId":"bme280_0x76"}}

{
  "jsonrpc":"2.0","id":2,
  "result":{"readings":[
    {"sensorId":"bme280_0x76","parameter":"temperature","value":22.4,"unit":"°C","timestamp":1234567890,"valid":true},
    {"sensorId":"bme280_0x76","parameter":"humidity","value":58.1,"unit":"%RH","timestamp":1234567890,"valid":true},
    {"sensorId":"bme280_0x76","parameter":"pressure","value":101320.0,"unit":"Pa","timestamp":1234567890,"valid":true}
  ]}
}

巴士历史

总线历史记录在循环RAM缓冲区中累积CAN帧、NMEA线路、解码的NMEA 2000消息和OBD-II记录。缓冲区的大小由可配置的RAM预算决定，其配置将持久化到LittleFS。

bus/history/read

type 必须是以下之一： can, nmea, nmea2000, obdii. limit 默认为所有存储的条目。

{"jsonrpc":"2.0","method":"bus/history/read","id":3,"params":{"type":"can","limit":10}}

{
  "jsonrpc":"2.0","id":3,
  "result":{
    "type":"can",
    "frames":["7E8#0441050300000000","7E8#04410D0000000000"],
    "count":2,
    "capacity":500
  }
}

{"jsonrpc":"2.0","method":"bus/history/read","id":4,"params":{"type":"nmea2000"}}

{
  "jsonrpc":"2.0","id":4,
  "result":{
    "type":"nmea2000",
    "messages":[
      {"pgn":129025,"priority":2,"source":0,"name":"Position Rapid Update",
       "valid":true,"hasPosition":true,"latitude":47.6097,"longitude":-122.3331}
    ],
    "count":1,"capacity":200
  }
}

{"jsonrpc":"2.0","method":"bus/history/read","id":5,"params":{"type":"obdii"}}

{
  "jsonrpc":"2.0","id":5,
  "result":{
    "type":"obdii",
    "records":[
      {"service":1,"pid":12,"name":"Engine RPM","value":1500,"unit":"rpm","valid":true},
      {"service":1,"pid":13,"name":"Vehicle Speed","value":65,"unit":"km/h","valid":true}
    ],
    "count":2,"capacity":300
  }
}

bus/history/config/get

{"jsonrpc":"2.0","method":"bus/history/config/get","id":6}

{
  "jsonrpc":"2.0","id":6,
  "result":{
    "canFrameCount":500,
    "nmeaLineCount":1000,
    "nmea2000Count":200,
    "obdiiCount":300,
    "ramBudgetBytes":1048576,
    "safetyMarginBytes":65536,
    "freeHeapBytes":2097152
  }
}

bus/history/config/set

所有字段都是可选的；省略的字段保留其当前值。

{
  "jsonrpc":"2.0","method":"bus/history/config/set","id":7,
  "params":{"canFrameCount":1000,"ramBudgetBytes":2097152}
}

{"jsonrpc":"2.0","id":7,"result":{"ok":true,"canFrameCount":1000,"nmeaLineCount":1000,"nmea2000Count":200,"obdiiCount":300,"ramBudgetBytes":2097152,"safetyMarginBytes":65536}}

集 canFrameCount, nmeaLineCount, nmea2000Count, obdiiCount 全部到 0 要启用自动调整大小：服务器拆分 ramBudgetBytes 根据每种记录类型的大小，在四种缓冲区类型之间相等。

指标

metrics/list

{"jsonrpc":"2.0","method":"metrics/list","id":8,"params":{"category":"system"}}

{
  "jsonrpc":"2.0","id":8,
  "result":{"metrics":[
    {"name":"system.heap.free","type":"gauge","description":"Free heap","unit":"bytes","category":"system"},
    {"name":"system.uptime","type":"counter","description":"Uptime","unit":"s","category":"system"},
    {"name":"system.wifi.rssi","type":"gauge","description":"WiFi signal strength","unit":"dBm","category":"system"}
  ]}
}

度量类型： counter （累积整数）， gauge （当前值）， histogram （最小/最大/平均/计数对象）。

metrics/get

{"jsonrpc":"2.0","method":"metrics/get","id":9,"params":{"name":"system.heap.free"}}

{
  "jsonrpc":"2.0","id":9,
  "result":{"name":"system.heap.free","type":"gauge","value":214032,"unit":"bytes","category":"system","timestamp":1234567890}
}

对于直方图度量， value 是一个对象： {"mean":…,"min":…,"max":…,"count":…}.

metrics/history

{"jsonrpc":"2.0","method":"metrics/history","id":10,"params":{"name":"system.heap.free","seconds":60}}

{
  "jsonrpc":"2.0","id":10,
  "result":{"name":"system.heap.free","entries":[
    {"ts":1234567800,"val":214100},
    {"ts":1234567830,"val":214032}
  ]}
}

日志

{"jsonrpc":"2.0","method":"logs/query","id":11,"params":{"name":"system.heap.free","seconds":120}}

{
  "jsonrpc":"2.0","id":11,
  "result":{"name":"system.heap.free","count":4,"entries":[
    {"ts":1234567810,"val":214100},
    {"ts":1234567840,"val":214032}
  ]}
}

{"jsonrpc":"2.0","method":"logs/clear","id":12}

{"jsonrpc":"2.0","id":12,"result":{"ok":true}}

订阅

{"jsonrpc":"2.0","method":"resources/subscribe","id":13,"params":{"uri":"sensor://i2c/bme280_0x76"}}

订阅后，服务器会主动推送 notifications/resources/updated 每次值更改时：

{"jsonrpc":"2.0","method":"notifications/resources/updated","params":{"uri":"sensor://i2c/bme280_0x76"}}

TypeScript客户端示例

看 examples/client/client.ts 对于一个完整的打字客户端。

______________________________________________________________________

I2C传感器参考

¹ humidity BMP280上没有。

______________________________________________________________________

NMEA 0183支持的句子

解析功能：XOR校验和验证、DDMM。MMMM → 符号十进制度数HHMMSS。SS时间，说话者ID提取，优雅的空白字段处理。

______________________________________________________________________

支持NMEA 2000 PGN

______________________________________________________________________

支持OBD-II PID（服务01）

已解码的选定PID；完整列表在 src/CANParser.cpp:

______________________________________________________________________

发现

在网络连接上，服务器注册了两个mDNS服务，并定期发送UDP能力信标：

mDNS和UDP在网络连接、I2C扫描完成、MCP服务器就绪和总线历史配置更改时自动触发。

______________________________________________________________________

测试

测试在Linux上本机编译和运行——不需要硬件。

# All tests
pio test -e native

# Specific suites
pio test -e native -f test_nmea_parser
pio test -e native -f test_can_parser
pio test -e native -f test_i2c_sensors
pio test -e native -f test_bus_reader
pio test -e native -f test_mcp_server
pio test -e native -f test_metrics_system

# With coverage (requires lcov)
pio test -e native --coverage

______________________________________________________________________

使用自定义MCP方法进行扩展

在运行时注册其他JSON-RPC处理程序：

mcpServer.registerMethodHandler("myns/doSomething",
    [](uint8_t clientId, uint32_t reqId, const JsonObject& params) {
        StaticJsonDocument doc;
        doc["result"]["ok"] = true;
        std::string out;
        serializeJson(doc, out);
        return out;
    });

// Remove when no longer needed
mcpServer.unregisterMethodHandler("myns/doSomething");

______________________________________________________________________

贡献

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/my-feature
3. 添加新功能的测试(pio test -e native 必须通过）
4. 打开拉取请求

看 贡献.md 关于编码风格和指导原则。

______________________________________________________________________

许可证

麻省理工学院——见 许可证.