rest980

You can run rest980 in a container using the official Docker image. This is useful for platforms like Synology. You must provide the BLID and PASSWORD via environment variables. You can also optionally provide the ROBOT_IP to skip discovery.

To pull and run the image:

$ docker pull koalazak/rest980
$ docker run -p 3000:3000 -e BLID=myuser -e PASSWORD=mypass -e ROBOT_IP=myrobotIP koalazak/rest980

To run rest980 from source, clone the repository, install dependencies via npm, and start the server. You can optionally enable debug logging by setting the DEBUG environment variable.

$ git clone https://github.com/koalazak/rest980.git
$ cd rest980
$ npm install
$ DEBUG=rest980:* npm start

The application exposes three main route prefixes. Note that the authHandler middleware is applied globally to all routes defined below it, meaning these endpoints are protected by Basic Authentication unless the user is whitelisted.

• /: Handled by helloRoute (index routes).
• /api: Handled by apiRoute (API endpoints).
• /map: Handled by mapRoute (Map-related endpoints).

The server uses Basic Authentication to protect routes. You can configure the required credentials using environment variables or the application configuration. If neither is provided, authentication is disabled.

Environment Variables:

• BASIC_AUTH_USER: The username for authentication.
• BASIC_AUTH_PASS: The password for authentication.

If authentication is enabled, any request to a non-whitelisted route without valid credentials will receive a 401 Unauthorized response with the header WWW-Authenticate: Basic realm=Authorization Required.

# Example using environment variables
export BASIC_AUTH_USER=admin
export BASIC_AUTH_PASS=secret_password

The bin/www script is the CLI entrypoint used to start the REST API server. It initializes the Express application and listens on a specified port. The server can be configured to run over HTTP or HTTPS depending on the presence of SSL certificate files.

# Assuming the package is installed and bin is in your PATH
rest980

# Or running directly via node if in the repository root
node bin/www

Perform cleaning actions using GET requests to /api/local/action/[action].

Standard Actions (GET):

• start, stop, pause, dock, resume, cleanRoom (Note: cleanRoom is a POST).

Example: Start cleaning GET http://<IP>:3000/api/local/action/start

Example: Clean a specific room (POST) For models like s9 or i7 with Smart Maps, use a POST request with a JSON body containing pmap_id, user_pmapv_id, and regions.

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"}'

Retrieve robot information using GET requests to /api/local/info/[record].

Available Records:

• mission: Current mission variables (flags, cycle, phase, battery, etc.).
• wireless: Wireless info.
• lastwireless: Last wireless info.
• sys: System info.
• sku: SKU info.
• state: Robot state (available in firmware 2 only).

Example: Get mission info GET http://<IP>:3000/api/local/info/mission

Manage robot configurations via /api/local/config/[configName]. Use GET to retrieve current settings and POST to update them.

Available Config Names:

• preferences: Main configuration (lang, timezone, name, cleaning preferences).
• carpetBoost/auto, carpetBoost/performance, carpetBoost/eco: Carpet boost settings (POST only).
• edgeClean/on, edgeClean/off: Edge cleaning (POST only).
• cleaningPasses/auto, cleaningPasses/one, cleaningPasses/two: Cleaning passes (POST only).
• alwaysFinish/on, alwaysFinish/off: Always finish setting (POST only).
• time: Time settings (POST/GET in firmware 1, GET only in firmware 2).

Example: Set cleaning passes to two (POST) POST http://<IP>:3000/api/local/config/cleaningPasses/two with body {}.

For firmware 1.6.x, you can access cloud-mapped methods via /api/cloud/. All endpoints use the GET method.

Cloud Info Endpoints:

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

Cloud Action Endpoints:

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

To enable HTTPS, provide paths to your SSL key and certificate files using the following environment variables. If both are provided, the server will automatically switch from HTTP to HTTPS mode.

• SSL_KEY_FILE: Path to the SSL key file.
• SSL_CERT_FILE: Path to the SSL certificate file.

If these environment variables are not set, the server will fall back to the sslKeyFile and sslCertFile values in your configuration file.

export SSL_KEY_FILE=/path/to/server.key
export SSL_CERT_FILE=/path/to/server.crt
node bin/www

You can specify the port the server listens on using the PORT environment variable. If PORT is not provided, the server falls back to the port value defined in your configuration file.

export PORT=8080
node bin/www