Zigqt

An alpine overlay to create a zigbee2mqtt hub on a Raspberry Pi
Explore the article »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
   • Additional Configuration
   • Further Customisation
3. Roadmap
4. Contributing
5. License
6. Contact

About The Project

This project was created after moving my Home Assistant install to a virtual machine, my server lives too far away for the zigbee dongle to reach, I wanted a small hub that I could plug-in and run zigbee2mqtt. I also wanted it to be low maintenance hence using Alpine and overlays, this way the OS runs diskless with a persistent disk for configuration, if it stops working, reboot and it will be back in the original state meaning less messing about when things go wrong.

Here we provide an overlay with all the necessary configuration to get you up and running, below are the main features:

• Support for DHCP unlike some other Pi Alpine overlays.
• Basic ssh server to log-into from another computer.
• mDNS record zigqt.local to easily connect.
• Installs zigbee2mqtt and enables web interface
• Add additional configuration based on samples to root without need to re-package overlay

(back to top)

Built With

This section should list any major frameworks/libraries used to bootstrap your project. Leave any add-ons/plugins for the acknowledgements section. Here are a few examples.

• 
• 
• 
• 

(back to top)

Getting Started

I recommend following this article Creating a standalone zigbee2mqtt hub using Alpine Linux, which includes downloading & creating installation media as well as applying this custom overlay. Tools provided here can be used on any platform for any install modes (diskless, data disk, system disk).

Prerequisites

• A RaspberryPi (recommend 3b+ or higher)
• Zigbee dongle (I use Conbee II)
• Micro SD Card
• Micro SD Card reader

The SD Card needs to be formatted into two partitions:

1. Boot Partition (512M Min Recommended)
2. Persistent Storage Partition (rest of the storage)

Installation

Just add zzigqt.apkovl.tar.gz overlay file to the root of Alpine Linux boot media and boot the system.

By default the image will get a DHCP Address assigned, /var, /etc/shaddow and /etc/zigbee2mqtt will be mapped to persistent storage.

Connect via SSH or HTTP using:

ssh [email protected]
http://zigqt.local:8080

As with Alpine Linux, initial boot, root account has no password (change this after setup).

Main execution steps are logged in /var/log/messages.

(back to top)

Additional Configuration

Add-on files may be added next to zigqt.apkovl.tar.gz to customise setup (sample files are provided):

• interfaces (optional): define network interfaces at will, if defaults DHCP-based are not suitable.
• wpa_supplicant.conf (mandatory for wifi use): define wifi SSID & password.
• configuration.yaml (optional): define configuration for zigbee2mqtt, a default configuration will be applied if not provided.
• secret.yaml (optional): define secrets for zigbee2mqtt, random will be generated on first boot if this is not provided.
• unattended.sh (optional): make custom automated deployment script to further tune & extend setup (backgrounded).

Note: these files are linux text files: Windows/macOS users need to use text editors supporting linux text line-ending (such as notepad++ or VSCode).

Goody: seamless USB bootstrapping for PiZero devices (or similar which can support USB ethernet gadget networking):
Just add dtoverlay=dwc2 in usercfg.txt (or config.txt), and plug-in USB to Computer port. With Computer set-up to share networking with USB interface as 10.42.0.1 gateway, one can log into device from Computer with ssh [email protected] !...

Further customisation

This repository may be forked/cloned/downloaded. Main script file is headless.sh. Execute ./make.sh to rebuild zigqt.apkovl.tar.gz.

(back to top)

Roadmap

• Add Issue templates
• Add Releases
• Add DHCP
• Add WiFi
• Add mDNS
• Persistent Zigbee2mqtt configuration

See the open issues for a full list of proposed features (and known issues).

(back to top)

Sponsors

My projects arent possible without the support of the community, please consider donating a small amount to keep these projects alive.

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "type/feature". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Discord Discussions

Project Link: https://github.com/totaldebug/zigqt

(back to top)

Acknowledgments

Below are a list of resources that I used to assist with this project.

• Alpine Linux Headless Bootstrap
• Alpine Linux on Raspberry Pi 4 Headless

(back to top)