diff --git a/README.md b/README.md index 58a7cb6..5acf664 100644 --- a/README.md +++ b/README.md @@ -5,38 +5,55 @@

I can't believe it's not Valetudo

-This is a simple map generation companion service for -[Valetudo](https://github.com/Hypfer/Valetudo), which does all the heavy -lifting. -Since both CPU and memory are limited on the robot, PNG generation for -third-party components has been moved here. The service receives raw map -data from the robot via MQTT, renders a map and publishes the resulting -PNG image via MQTT. +ICBINV is a companion service for Valetudo that renders ValetudoMap map data to raster graphics. -Please note that in most setups, ICBINV will **not** be required.
-Furthermore, note that this service is only maintained on a very basic level. +Incoming ValetudoMap Data is received via MQTT. +Rendered map images are published to MQTT and can optionally also be requested via HTTP (if enabled) + +Please note that this service is only maintained on a very basic level. + +## Why would I need this? + +If you're using Home Assistant, you probably don't as the custom valetudo lovelace map card does a much better job +than ICBINV while also being way easier to install, update and use. + +If you however use FHEM, OpenHAB or similar, this might be the only way to view the map data using your home automation system. ## Installation -*I can't believe it's not Valetudo* is built with JavaScript and requires -Node.js and npm to run. +The recommended install method for ICBINV is to clone the repo and then use the provided Dockerfile. + +With docker-compose, it would look something like this: + +``` + icantbelieveitsnotvaletudo: + build: + context: ./ICantBelieveItsNotValetudo/ + dockerfile: Dockerfile + container_name: "ICantBelieveItsNotValetudo" + restart: always + volumes: + - /opt/docker_containers/ICantBelieveItsNotValetudo/config.json:/app/config.json +``` -Installation is easy: Clone this repository and run `npm install` to -install dependencies. Then run `npm start` to start the service. -If you prefer running services in containers, this repository includes -a dockerfile for you. +If you have multiple robots, simply deploy multiple instances of ICBINV. + + +If you don't want to use docker, you will need to install a recent nodejs version + npm installed on your host. + +First, install the dependencies with `npm ci`. Then, you can start the application by running `npm run start`. ## Configuration -To configure *I can't believe it's not Valetudo*, create a file called -`config.json` in the working directory. You can also run `npm start` to -automatically create a default configuration file. If you are running in -docker, map the configuration file to `/app/config.json` . +To configure *I can't believe it's not Valetudo*, create a file called `config.json` in the working directory. +You can also run `npm start` to automatically create a default configuration file. + +If you are running in docker, map the configuration file to `/app/config.json` . ## Integration with FHEM, ioBroker, openHAB etc -If you set `webserver.enabled` to `true`, the map PNG will be available -at `http://host:port/api/map/image` so you can display a map with any -home automation software that allows fetching images from a URL. -The map will also be available as base64-encoded string at -`http://host:port/api/map/base64`. -By default, the image data is published via MQTT to `mqtt.topicPrefix/mqtt.identifier/MapData/map`, if `mqtt.publishAsBase64` is set to `true`, the image data is published as base64-encoded string (a.e. for openHAB). + +Enabling the webserver in the configuration file will allow you to fetch the latest rendered map image via `http://host:port/api/map/image`.
+The map will also be available as base64-encoded string at `http://host:port/api/map/base64`. + +By default, the image data is published via MQTT to `mqtt.topicPrefix/mqtt.identifier/MapData/map` as a raw binary image.
+If `mqtt.publishAsBase64` is set to `true`, the image data will instead be published as base64-encoded string, which can be useful for OpenHAB.