koalazak/rest980 Docker 镜像 - 轩辕镜像 | Docker 镜像高效稳定拉取服务

rest980

rest980是一个HTTP服务器，可将dorita980库的所有方法映射为REST API，从而通过HTTP请求控制iRobot Roomba 900系列（980/i7/i7+）扫地机器人。

镜像概述和主要用途

rest980旨在提供一个便捷的REST API接口，让用户能够通过HTTP请求远程控制Roomba机器人，支持本地和云两种控制方式，适用于家庭自动化、远程监控等场景。

核心功能和特性

• 将dorita980的方法映射为REST API，支持本地和云接口
• 可通过配置文件或环境变量灵活配置服务参数
• 支持基本认证和HTTPS加密
• 提供Docker镜像，便于快速部署（如在Synology等设备上运行）
• 支持静态文件服务和实验性实时地图功能

使用场景和适用范围

适用于需要通过HTTP协议控制iRobot Roomba 900系列（980/i7/i7+）机器人的场景，包括但不限于：

• 家庭自动化系统集成
• 远程控制机器人清洁、暂停、返回充电等操作
• 获取机器人状态信息（电量、清洁任务等）
• 自定义机器人清洁配置

详细使用方法和配置说明

固件版本要求

检查您的机器人固件版本，并在rest980配置中设置firmwareVersion参数！

配置参数

服务可通过编辑config/default.json文件或设置环境变量进行配置：

有关获取BLID和密码的更多信息和说明，请参见dorita980

Docker部署

拉取Docker镜像

bash
docker pull koalazak/rest980

运行Docker容器

bash
docker run -e BLID=myuser -e PASSWORD=mypass -e ROBOT_IP=myrobotIP koalazak/rest980

本地构建Docker镜像

可通过项目中的Dockerfile本地构建：

bash
docker build . -t koalazak/rest980

API使用说明

服务启动后，可通过端口3000访问API，主要包含local（本地）和cloud（云）两个端点，分别对应dorita980的本地和云方法。

错误响应

HTTP状态码500，响应格式：

json
{"message":"人类可读消息","error":{}}

本地API（local）

操作接口（Actions）

所有清洁操作通过/api/local/action/[action]端点，使用GET方法（无查询参数）：

可用操作：

• start（开始清洁）
• stop（停止）
• pause（暂停）
• dock（返回充电）
• resume（恢复）
• cleanRoom（指定房间清洁）

示例：开始清洁

http
GET http://192.168.1.110:3000/api/local/action/start

成功响应：

json
{"ok":null,"id":23}

示例：指定房间清洁

部分Roomba型号（如s9、i7）支持房间特定清洁，需通过POST方法发送参数：

sh
curl -X POST http://192.168.1.110:3000/api/local/action/cleanRoom -H 'Content-Type: application/json' -d '{"ordered": 0, "pmap_id": "123456", "regions": [{"region_id":"5", "region_name":"Hallway","region_type":"hallway"}], "user_pmapv_id": "987654"}'

信息接口（Info）

所有信息通过/api/local/info/[record]端点，使用GET方法（无查询参数）：

可用记录：

• mission（任务状态）
• wireless（无线信息）
• lastwireless（最近无线信息）
• sys（系统信息）
• sku（型号信息）
• state（状态，仅固件2支持）

示例：获取当前任务变量

http
GET http://192.168.1.110:3000/api/local/info/mission

成功响应：

json
{ "ok":
   { "flags": 0,
     "cycle": "none",
     "phase": "charge",
     "pos": { "theta": 179, "point": {"x": 102, "y": -13} },
     "batPct": 99,
     "expireM": 0,
     "rechrgM": 0,
     "error": 0,
     "notReady": 0,
     "mssnM": 0,
     "sqft": 0 },
  "id": 2 }

配置接口（Configurations）

所有配置通过/api/local/config/[configName]端点，GET方法获取配置，POST方法设置配置：

可用配置名称：

• ptime（仅固件1支持GET）
• bbrun（仅GET）
• cloud（仅GET）
• langs（仅GET，通过preferences设置语言）
• week
• time（固件1支持POST和GET，固件2仅支持GET）
• preferences
• carpetBoost/auto（仅POST，通过preferences获取当前配置）
• carpetBoost/performance（仅POST）
• carpetBoost/eco（仅POST）
• edgeClean/on（仅POST）
• edgeClean/off（仅POST）
• cleaningPasses/auto（仅POST）
• cleaningPasses/one（仅POST）
• cleaningPasses/two（仅POST）
• alwaysFinish/on（仅POST）
• alwaysFinish/off（仅POST）

示例：获取固件1的偏好设置

http
GET http://192.168.1.110:3000/api/local/config/preferences

成功响应：

json
{ "ok":
   { "flags": 1024,
     "lang": 2,
     "timezone": "America/Buenos_Aires",
     "name": "myRobotName",
     "cleaningPreferences": {
        "carpetBoost": "auto",
        "edgeClean": true,
        "cleaningPasses": "1",
        "alwaysFinish": true 
      }
    },
 "id": 2 }

示例：设置清洁次数为两次

http
POST http://192.168.1.110:3000/api/local/config/cleaningPasses/two

请求体：

json
{}

成功响应：

json
{"ok":null,"id":293}

云API（cloud，仅固件1.6.x支持）

所有信息接口使用GET方法（无查询参数）：

• /api/cloud/info/status
• /api/cloud/info/history
• /api/cloud/info/missionHistory

所有操作接口使用GET方法（无查询参数）：

• /api/cloud/action/clean
• /api/cloud/action/quick
• /api/cloud/action/spot
• /api/cloud/action/dock
• /api/cloud/action/start
• /api/cloud/action/stop
• /api/cloud/action/pause
• /api/cloud/action/resume
• /api/cloud/action/wake
• /api/cloud/action/reset
• /api/cloud/action/find
• /api/cloud/action/wipe
• /api/cloud/action/sleep
• /api/cloud/action/off
• /api/cloud/action/fbeep

示例：开始清洁

http
GET http://192.168.1.110:3000/api/cloud/action/clean

成功响应：

json
{"status":"OK","method":"multipleFieldSet"}

静态文件服务

可将图片或文件添加到public/文件夹，服务将提供静态文件访问。

实验性实时地图

通过浏览器访问http://serverIP:3000/map，可体验实验性实时地图功能。

!实时地图

视频演示：使用dorita980库的iRobot Roomba 980清洁地图