flopon/valetudo-mapper

Valetudo Mapper 镜像文档

镜像概述

Valetudo Mapper 是 Valetudo 的配套服务，专为处理资源密集型任务而设计。由于扫地机器人的 CPU 和内存资源有限，地图 PNG 生成等繁重任务被迁移至此服务，以减轻机器人的运行负担。该镜像提供自动化构建，可通过 Docker 便捷部署。

核心功能与特性

• 地图生成：负责生成 PNG 格式的地图图像，支持自定义颜色、绘制选项及图像裁剪
• MQTT 集成：通过 MQTT 协议与 Valetudo 及第三方组件（如 Home Assistant）通信
• 配置灵活：支持自定义地图颜色、绘制元素（路径、充电器、机器人位置等）、图像裁剪与旋转
• 轻量级 Web 服务：可选启用内置 Web 服务器，提供地图 PNG 访问接口
• 多实例支持：可通过不同配置文件运行多个实例，满足多机器人或多场景需求

使用场景与适用范围

• Home Assistant 集成：为 Home Assistant 提供静态 PNG 地图图像（当 JavaScript 不可用时）
• FHEM、ioBroker 等智能家居平台：通过 Web 服务器接口获取地图图像
• 多机器人环境：通过多实例部署管理多个扫地机器人的地图生成任务

使用方法与配置说明

Docker 部署

基本运行命令

bash
docker run -d \
  --name valetudo-mapper \
  -v /path/to/your/config.json:/app/config.json \
  rand256/valetudo-mapper

多实例运行

通过指定不同配置文件运行多个实例：

bash
docker run -d \
  --name valetudo-mapper-robot1 \
  -v /path/to/robot1/config.json:/app/config.json \
  rand256/valetudo-mapper

docker run -d \
  --name valetudo-mapper-robot2 \
  -v /path/to/robot2/config.json:/app/config.json \
  rand256/valetudo-mapper

配置文件说明

配置文件需映射到容器内的 /app/config.json，包含以下核心配置项：

MQTT 配置 (mqtt)

地图设置 (mapSettings)

颜色配置：自定义地图各元素颜色

json
"colors": {
  "background": "#33a1f5",          // 背景色
  "background2": "#046cd4",         // 背景色2（渐变背景时使用）
  "floor": "#56affc",               // 地板颜色
  "obstacle_strong": "#a1dbff",     // 强障碍物颜色
  "path": "white",                  // 路径颜色
  "forbidden_marker": "red",        // 禁区标记颜色
  "forbidden_zone": "rgba(255, 0, 0, 0.38)", // 禁区区域颜色
  "cleaned_marker": "rgba(53, 125, 46, 1.0)", // 已清洁标记颜色
  "cleaned_zone": "rgba(107, 244, 66, 0.3)", // 已清洁区域颜色
  "cleaned_block": "rgba(107, 244, 36, 0.34)" // 已清洁块颜色
}

绘制选项：控制地图元素显示

json
"drawPath": true,                  // 是否绘制路径
"drawCharger": true,               // 是否绘制充电器位置
"drawRobot": true,                 // 是否绘制机器人位置
"drawCurrentlyCleanedZones": false, // 是否绘制当前清洁区域
"drawCurrentlyCleanedBlocks": false, // 是否绘制当前清洁块
"drawForbiddenZones": true,        // 是否绘制禁区
"drawVirtualWalls": true           // 是否绘制虚拟墙

图像处理：调整地图尺寸、裁剪与旋转

json
"scale": 4,                        // 缩放比例
"gradientBackground": true,        // 是否使用渐变背景
"autoCrop": 20,                    // 自动裁剪边界像素（移除边缘空白）
"crop_x1": 30,                     // 手动裁剪左上角X坐标
"crop_y1": 70,                     // 手动裁剪左上角Y坐标
"crop_x2": 440,                    // 手动裁剪右下角X坐标
"crop_y2": 440,                    // 手动裁剪右下角Y坐标
"rotate": 90                       // 旋转角度（度）

Web 服务器配置 (webserver)

启用后，地图 PNG 可通过 http://host:port/api/map/image 访问。

配置文件示例

完整配置文件示例：

json
{
  "mqtt": {
    "identifier": "rockrobo",
    "topicPrefix": "valetudo",
    "autoconfPrefix": "homeassistant",
    "broker_url": "mqtt://user:pass@example.com:port",
    "caPath": "",
    "mapDataTopic": "valetudo/rockrobo/map_data",
    "minMillisecondsBetweenMapUpdates": 10000,
    "publishMapImage": true,
    "publishMapData": false
  },
  "mapSettings": {
    "colors": {
      "background": "#33a1f5",
      "background2": "#046cd4",
      "floor": "#56affc",
      "obstacle_strong": "#a1dbff",
      "path": "white",
      "forbidden_marker": "red",
      "forbidden_zone": "rgba(255, 0, 0, 0.38)",
      "cleaned_marker": "rgba(53, 125, 46, 1.0)",
      "cleaned_zone": "rgba(107, 244, 66, 0.3)",
      "cleaned_block": "rgba(107, 244, 36, 0.34)"
    },
    "drawPath": true,
    "drawCharger": true,
    "drawRobot": true,
    "drawCurrentlyCleanedZones": false,
    "drawCurrentlyCleanedBlocks": false,
    "drawForbiddenZones": true,
    "drawVirtualWalls": true,
    "scale": 4,
    "gradientBackground": true,
    "autoCrop": 20,
    "crop_x1": 30,
    "crop_y1": 70,
    "crop_x2": 440,
    "crop_y2": 440,
    "rotate": 90
  },
  "webserver": {
    "enabled": false,
    "port": 3000
  }
}

地图示例

在 Home Assistant 中显示的地图 PNG 示例：

!地图示例

静态光栅图像虽不如浏览器通过 HTML Canvas 生成的图像清晰，但在 JavaScript 不可用的场景下可满足需求。