Configuration

RoomHub configurator installation

Download latest version of RoomHub Configurator for your operating system:

After extracting downloaded archive - executable file is located in bin/room-hub-configurator (for Un*x) or bin/room-hub-configurator.bat (for Windows).

RoomHub configuration process

Info

If you have configured your RoomHub earlier - you may want to start with resetting devices configuration and/or WiFi connection.

  1. Make sure RoomHub has WiFi connection configured or using ethernet connection with W5500. Keep in mind that different firmware needs to be used for wired connection.
  2. Prepare configuration file.

  3. Run configurator to send configuration to RoomHub

    bin/room-hub-configurator your-file.roomhub.yml

    bin/room-hub-configurator your-file.roomhub.yml

    bin/room-hub-configurator.bat your-file.roomhub.yml

  4. Observe logs to check if configuration has been applied successfully.

  5. RoomHub will be automatically restarted if configuration has been finished. In case of errors you can correct configuration file and run configurator again without restarting RoomHub.

You can subscribe to MQTT topic homie/YourRoomHubName/# to see if RoomHub has correctly started with new configuration.

[TODO: add asciinema showing configuration process]

RoomHub configuration file

RoomHub configuration file is written in YAML format. You can use basic text editor to create this file, but if you are using more advanced editor (like VSCode) then you can use JSON schema for autocompletion and validation.

The structure of the file is like:

configVersion: "3.0" # version of this config file format (leave unchanged)
name: "YourRoomHubName" # name of RoomHub used in MQTT topic
destinationIpAddress: "192.168.1.66" # IP of RoomHub (e.g. from EspTouch)
mqttHostname: "192.168.1.52" ## address of MQTT server
network: # Ethernet configuration - put anything when running on WiFi
  macAddress: "6D:CB:54:AD:E9:93"
  ipAddress: "192.168.1.66"
rooms: # list of rooms
  - name: "bathroom"
    points: # list of points
      - name: "bathroom light switch box"
        portNumber: 1
        devices: # list of devices
          - name: "bathroom light" # name of device
            id: 1 # identifier of device (unique in this configuration file)
            wires: ["BLUE"] # list of ethernet wires used for connection
            type: RELAY # type of device
          - name: "bathroom light switch"
            id: 2
            wires: ["BLUE_WHITE"]
            type: SWITCH_BUTTON
            config: # some devices has additional config options
              debounceMs: 50

See naming convention page to find explanation of terms like "point".

Reset devices configuration

To reset configuration (device name, MQTT hostname and devices) keep button 2 (on Mainboard) pressed for 5 seconds when restarting RoomHub.

  1. Make sure RoomHub is connected to power socket
  2. Keep button 2 pressed on mainboard (see image below)
  3. Reset RoomHub by shortly pressing EN button on ESP32
  4. Release button 2 when blue LED will start blinking on ESP32

ESP32 will indicate configuration reset by blinking 3 times with blue LED.

After configuration reset, RoomHub will restart and start server waiting for new configuration.

RoomHub buttons

WiFi configuration

WiFi configuration is done with ESP Touch Smart Config

You need Android or iOS smartphone to configure WiFi on RoomHub. First reset existing RoomHub WiFi configuration and then configure it with app on your mobile.

Reset WiFi configuration

To reset WiFi setup, keep button 1 on mainboard pressed for 5 seconds when restarting RoomHub.

  1. Make sure RoomHub is connected to power socket
  2. Keep button 1 pressed on mainboard (see image)
  3. Reset RoomHub by pushing "EN" button on ESP32 for a moment
  4. Release button 1 when blue LED will start blinking on ESP32

ESP32 will indicate WiFi configuration reset by blinking 5 times with blue LED.

After WiFi configuration reset, RoomHub will restart and start in ESP Smart Config WiFi mode.

Android

  1. Install EspTouch from Google Play.
  2. Connect your phone to WiFi network you want RoomHub to be connected to
  3. Open EspTouch and insert password
  4. Press "confirm"
  5. After around 30 seconds you should get success message with IP address of RoomHub - store this IP address for later

EspTouch Android - step 1 EspTouch Android - step 2 EspTouch Android - step 3

iPhone (iOS)

  1. Install Espressif Esptouch from App Store.
  2. Connect your phone to WiFi network you want RoomHub to be connected to
  3. Open EspTouch and insert password
  4. Press "confirm"
  5. After around 30 seconds you should get success message with IP address of RoomHub - store this IP address for later

EspTouch iOS - step 1 EspTouch iOS - step 2