A modern, fast, and responsive Progressive Web App (PWA) for your CCU3 with an integrated WebSocket server.
Whether you're a developer looking to contribute or a user seeking a better interface for your CCU3, this project has something for you. Dive in to explore the features, installation steps, and how you can get involved.
My motivation was to have a user-friendly app for the tablet in our kitchen, allowing us to conveniently control all devices in the house.
This project is built with a robust set of technologies to ensure high performance and maintainability:
- React: A JavaScript library for building user interfaces.
- TypeScript: A strongly typed superset of JavaScript that adds static types.
- Emotion: A library designed for writing CSS styles with JavaScript.
- WebSocket: Two-way interactive communication between browser and server.
- Vite: Next generation frontend tooling.
- Nx: Smart, fast and extensible build system.
- Bun: Fast all-in-one JavaScript runtime and bundler.
- TypeScript: Type-safe server code.
- WebSocket Server: WebSocket implementation for Node.js.
- Homematic Libraries: XML-RPC and ReGa script support.
Configure Rooms and or Trades (Gewerke) and Assign Channels (Devices)
To ensure this add-on functions properly, you need to have rooms or trades configured in your CCU3. Each room should have channels assigned with appropriate names, as the add-on queries the rooms, their channels, and the datapoints of those channels. Without this setup, the add-on will not work.
To install this add-on:
- Download the latest addon
tar.gzfile from the releases page. - Install it as a plugin on your CCU3 via the settings page under "Additional Software".
- Please Note: Upload and Reboot takes some time, depending on your Box ccu3 vs raspberry. (This is because we need to copy the nodejs binary)
- The add-on will be available at
http://192.168.178.111/addons/mui(replace with your CCU IP).
Note: Node-RED is no longer required! This add-on now includes its own integrated WebSocket server that:
- Runs natively on the CCU3
- Uses port 8183 for local ReGa connections (no authentication needed)
- Automatically handles CCU events via XML-RPC
- Provides real-time updates via WebSocket
The CCU3 will automatically check for new versions via GitHub Releases. When an update is available:
- Go to Settings → Additional Software
- Check for updates
- Download and install the new version
In the latest Chrome version, Progressive Web App (PWA) features and WakeLock only work with HTTPS. You need to set up the IP of your CCU3 as a secure origin.
- Open Chrome and go to
chrome://flags. - Search for
Insecure origins treated as secure - Enter IP Adress of CCU3 e.g.
http://192.168.178.111(replace with your IP). - Enable
- Save and relaunch Chrome
Progressive Web Apps (PWAs) can be installed on your device like native apps. Follow these steps to add our PWA to your home screen:
- Open the PWA in your browser (e.g., Chrome, Firefox).
- Tap the browser's menu (usually three dots in the top right corner).
- Select "Add to Home screen".
- Open the PWA in Safari.
- Tap the Share button (the box with an upward arrow).
- Scroll down and select "Add to Home Screen".
After these steps, the PWA will appear as an icon on your home screen, and you can use it just like a native app.
To perevent the PWA from going into standby, we use the WakeLock API.
Steps to enable WakeLock experimental API in Chrome:
NOTE: The WakeLock API may no longer be experimental by the time you read this.
- Open Chrome and go to
chrome://flags. - Search for and enable
Experimental Web Platform features. - Save and relaunch Chrome.
After these steps, the WakeLock API should be enabled, preventing your screen from going into standby while using the PWA.
To verify if WakeLock is working, check the browser console for the following error:
This error indicates the WakeLock API is unavailable, review the steps above.
This project currently supports the following devices:
Channel Type: SWITCH_VIRTUAL_RECEIVER
Features:
- Display Light Status
- Switch Light On/Off
Channel Type: HEATING_CLIMATECONTROL_TRANSCEIVER
Features:
- Show Current Humidity
- Show Target Temperature
- Show Current Temperature
- Show Window Open State
- Set Target Temperature
Channel Type: BLIND_VIRTUAL_RECEIVER
Features:
- Show open percentage
- Open/Close
- Stop
- Set the open percentage of the blinds by clicking on them
For this to work properly, you need to measure and configure the opening and closing times for your blinds in the CCU3.
Channel Type: KEYMATIC
Features:
- Show Door Status
- Unlock Door
- Lock Door
- Open Door
Channel Type: CLIMATECONTROL_FLOOR_TRANSCEIVER
Features:
- Display the opening percentage of the floor heating valve
- Set target temperature
- Show current temperature
The current user interface represents a responsive version of the rooms view of the CCU3.
Here you see all rooms configured in the ccu3, and you can select the room in which you want to see or modify channels.
This is the channels view.
Here you can see and change the state of the channels associated with the selected room.
To build this project, you need:
- Node.js (v18 or higher) - for npm and build tools
- Bun (latest) - for bundling the WebSocket server
# Install Bun curl -fsSL https://bun.sh/install | bash
To develop and build this project, follow these steps:
- Clone the repository:
git clone https://github.com/firsttris/ccu-addon-mui.git - Navigate into the project directory:
cd ccu-addon-mui - Install the dependencies:
npm install - Set your CCU3 IP in: proxy.config.json
- Start the development server:
npm start - To build the project, use:
npm run build
This will:
- Build the frontend React app
- Bundle the WebSocket server with all dependencies
- Download the Node.js ARM32 binary for CCU3
- Create a
.tar.gzaddon package ready for installation
To test your WebSocket connection, you can use the WebSocket Test Client Chrome Addon:
- Open the WebSocket Test Client and go to "Options".
- Enter your WebSocket Endpoint URL:
ws://192.168.178.111/addons/red/ws/webapp(replace with your actual IP). - Press "Connect". (Status "OPEN" indicates a successful connection.)
- Test the connection by sending the content of the getRooms.tcl script as payload.
I have collected an API Summary, where you have an quick overview of all methods for the different homematic API's
Want to start contributing to this project?
Please visit our issues page for the latest issues and feature requests.
We welcome pull requests to add features or support for new devices. Your contributions are appreciated!