Installation

At a glance

ℹ️ <owner> in the commands stands for the account that hosts the repository. If you received the sources as an archive, skip git clone and work in the unpacked folder.

Two things have to be installed: the module on the mirror and the adapter in ioBroker. Do them in this order — the adapter needs the module to talk to.

Part A · MagicMirror² module MMM-ioBrokerBridge

Requirements: MagicMirror² 2.30 or newer, Node.js 20 or newer, git on the mirror (it is used to install modules from the catalogue).

Step 1 · Copy the module into the modules folder

cd ~/MagicMirror/modules            # Docker: the host folder that is mounted as "modules"
git clone https://github.com/<owner>/iobroker-magicmirror.git /tmp/iobroker-magicmirror
cp -r /tmp/iobroker-magicmirror/MMM-ioBrokerBridge .
rm -rf /tmp/iobroker-magicmirror

The module has no dependencies — there is no npm install to run.

Step 2 · Create an access token

openssl rand -hex 24

Keep the output; you need it once on the mirror and once in ioBroker.

Step 3 · Give the token to MagicMirror as an environment variable

The token does not go into config.js: MagicMirror serves that file in plain text under /config/config.js.

Docker (docker-compose.yml):

services:
  magicmirror:
    environment:
      - MM_IOBROKER_TOKEN=<your token>
    volumes:
      - ./config:/opt/magic_mirror/config
      - ./modules:/opt/magic_mirror/modules   # the whole folder, so that installed modules survive

Mount the whole modules folder, not single module folders. Otherwise modules installed from ioBroker live only inside the container and are gone when it is recreated.

pm2:

MM_IOBROKER_TOKEN=<your token> pm2 restart mm --update-env
pm2 save

systemd: add Environment=MM_IOBROKER_TOKEN=<your token> to the [Service] section of the unit, then sudo systemctl daemon-reload.

Step 4 · Add the module to config/config.js

modules: [
    // … your other modules …
    {
        module: "MMM-ioBrokerBridge",
        config: { heartbeat: 10000 }
    }
]

No position is needed — the module draws nothing.

Step 5 · Restart MagicMirror

docker compose up -d          # Docker (recreates the container with the new environment)
pm2 restart mm                # pm2

Step 6 · Check

curl http://<mirror>:8080/MMM-ioBrokerBridge/health
# {"ok":true,"bridge":"1.0.0","mmVersion":"2.37.0","tokenConfigured":true}

curl -H "Authorization: Bearer <your token>" http://<mirror>:8080/MMM-ioBrokerBridge/api/status
# a JSON document with versions, modules and statistics

"tokenConfigured":true and a JSON answer from /api/status mean the mirror side is ready.

Part B · ioBroker adapter magicmirror

Requirements: js-controller 5 or newer, Admin 6 or newer, Node.js 20 or newer. The ioBroker host must be able to reach the mirror over HTTP (test: curl http://<mirror>:8080/MMM-ioBrokerBridge/health from the ioBroker host).

Step 1 · Build the package

git clone https://github.com/<owner>/iobroker-magicmirror.git
cd iobroker-magicmirror/iobroker.magicmirror
npm pack                            # creates iobroker.magicmirror-1.0.0.tgz

Step 2 · Install it into ioBroker

cd /opt/iobroker
npm install /path/to/iobroker.magicmirror-1.0.0.tgz --omit=dev

ioBroker in Docker: copy the file into the container first.

docker cp iobroker.magicmirror-1.0.0.tgz iobroker:/tmp/
docker exec iobroker bash -lc 'cd /opt/iobroker && npm install /tmp/iobroker.magicmirror-1.0.0.tgz --omit=dev'

Prefix the following iobroker … commands with docker exec iobroker in that case.

Step 3 · Upload the admin files and create the instance

iobroker upload magicmirror
iobroker add magicmirror 0

Step 4 · Configure the instance

In the Admin: Instances → magicmirror.0 → 🔧

Click Check connection — the answer should read Connected: MagicMirror v… — then Save.

On the command line instead:

iobroker set magicmirror.0 --host <mirror> --port 8080
iobroker object set system.adapter.magicmirror.0 native.token=<your token>

⚠️ Do not set the token with iobroker set … --token: that command stores it unencrypted and the adapter then reads garbled characters. iobroker object set encrypts it.

Step 5 · Open the tab

Reload the Admin page. The side menu now has an entry MagicMirror. If it is missing, click the pencil at the top of the side menu and switch the entry on.

Step 6 · Check

iobroker state getValue magicmirror.0.info.connection     # true
iobroker state getValue magicmirror.0.info.mmVersion      # e.g. 2.37.0

Updating

# mirror: replace the folder modules/MMM-ioBrokerBridge with the new version, then restart MagicMirror
# ioBroker:
cd iobroker.magicmirror && npm pack
cd /opt/iobroker && npm install /path/to/iobroker.magicmirror-<version>.tgz --omit=dev
iobroker upload magicmirror && iobroker restart magicmirror.0

Troubleshooting

What it looks like afterwards