LN Nix User Group: Making a NixOS module

lnnixug-nixos-module.md

LN Nix User Group - Making a NixOS Module

Background

Home Assistant

I use Home Assistant on a NixOS server at home.

Home Assistant is an open-source home automation system, designed to be a central control system for smart home devices with a focus on local control and privacy. It's implemented in Python and has a bewildering array of integrations, so in turn it has a huge number of depdendencies!

There's a great [Home Assistant NixOS module] that allows declarative configuration of Home Assistant.

Z-Wave

Z-Wave is a wireless technology for home automation. It can be used to control things like lights, power switches, sensors etc. To use it, you need a Z-Wave controller.

zwave-js and Home Assistant

There are several ways to integrate Home Assistant with Z-Wave controllers, but the best seems to be via Z-Wave JS. There is a Z-Wave JS Integration that talks to Z-Wave JS Server via a WebSocket. zwave-js-server was actually packaged in Nixpkgs, but there was no NixOS module to run it!

Adding a zwave-js NixOS module

Want to achieve something like this:

  # Z-Wave
  services.zwave-js = {
    enable = true;
    serialPort = "/dev/ttyUSB0";
  };

Like other NixOS modules, this should do a bunch of things:

• Install the zwave-js-server package
• Generate relevant config files
• Create a systemd service to run it, with appropriate settings
• Wire all these things together

The PR: NixOS/nixpkgs#230380

Problems to overcome

• Secrets: we don't want them in plain text in the NixOS config, or the Nix store
• Testing: NixOS has great test infrastructure, but we don't want to require a real Z-Wave controller to test
• Writing a good module!

Feedback received

• Converting npm package from buildNodePackage to buildNpmPackage
• systemd hardening (user/group, privileges)
• Module interface and documentation
• Structural settings (RFC 0042

Also implemented RFC 0140.

Stats:

• Took six months from creation to merge (mostly due to long gaps in me working on it!)
• Lots of good feedback from @mweinelt, @dotlambda, @h7x4
• At least 26 different changes suggested/updates made

The final module! https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/home-automation/zwave-js.nix