initial commit

1 files changed, 124 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ae322a6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,124 @@
+# open-bamboo-networking (Nix/home-manager)
+
+Nix packaging of [open-bamboo-networking](https://github.com/ClusterM/open-bamboo-networking),
+an open-source drop-in replacement for the proprietary `bambu_networking`
+plugin.
+
+The proprietary plugin (which OrcaSlicer will try to download) is not
+compatible with NixOS unless you go through the effort of (at the very least)
+relinking the shared objects (`libBambuSource.so` +
+`libbambu_networking_xx.xx.xx.xx.so`) downloaded to the plugins directory
+(`~/.config/OrcaSlicer/plugins`). The open plugin, on the other hand, can be
+easily built with Nix and the binaries can be dropped into the plugins
+directory to replace the proprietary ones.
+
+The flake includes also a home-manager module which installs the plugin for
+OrcaSlicer decoratively. One caveat is that `OrcaSlicer.conf` will need to be
+patched in order for it to recognize the plugin when it is (as in this case)
+installed manually (see instructions below). Correctly done, the user will not
+be notified of a missing plugin on launch.
+
+## Usage
+
+```nix
+{
+  inputs.open-bamboo-networking.url = "github:you/open-bamboo-networking";
+
+  # in your home-manager config:
+  imports = [ inputs.open-bamboo-networking.homeManagerModules.default ];
+
+  programs.openBambooNetworking = {
+    enable = true;
+    orcaSlicer = {
+      enable = true; # default
+    };
+  };
+}
+```
+
+### Options
+
+| option | default | description |
+|---|---|---|
+| `programs.openBambooNetworking.enable` | `false` | enable the module |
+| `programs.openBambooNetworking.orcaSlicer.enable` | `true` | build and link the plugin for OrcaSlicer / a compatible fork |
+| `programs.openBambooNetworking.orcaSlicer.obnVersion` | `"02.03.00.99"` | ABI version baked into the built filename |
+| `programs.openBambooNetworking.orcaSlicer.configDir` | `${config.xdg.configHome}/OrcaSlicer` | where `OrcaSlicer.conf` and `plugins/` live - override for forks, nightlies, or Flatpak installs |
+
+`orcaSlicer.enable` only links the shared objects declaratively into
+`<configDir>/plugins` - it does **not** touch `OrcaSlicer.conf`. That file
+is mutable app state the slicer reads and rewrites on its own, so patching
+it is left as a manual step (below) rather than something
+`home-manager switch` does for you.
+
+## Patching OrcaSlicer.conf
+
+After `home-manager switch`, and after launching the slicer at least once
+so `<configDir>/OrcaSlicer.conf` exists, run:
+
+```bash
+# Ensure correct $ver
+cat <<< $(jq --arg ver "02.03.00.99" '
+  .app.installed_networking = "true"
+  | .app.network_plugin_version = $ver
+  | .app.network_plugin_remind_later = "true"
+' ~/.config/OrcaSlicer/OrcaSlicer.conf) > ~/.config/OrcaSlicer/OrcaSlicer.conf
+```
+
+Use the same `$ver` as `orcaSlicer.obnVersion`. Restart the slicer. Re-run
+this whenever you change `obnVersion`, or if the app ever resets
+`network_plugin_version` on its own.
+
+### Automating it with home.activationScripts
+
+If you'd rather this happen automatically on every `home-manager switch`
+instead of by hand, add this alongside the module import. It reads
+`obnVersion`/`configDir` straight from `programs.openBambooNetworking.orcaSlicer`,
+so it can't drift out of sync with what the module actually built and
+linked:
+
+```nix
+{ config, lib, pkgs, ... }:
+let
+  cfg = config.programs.openBambooNetworking.orcaSlicer;
+in
+{
+  home.activationScripts.openBambooNetworkingOrcaConf = ''
+    CONF="${cfg.configDir}/OrcaSlicer.conf"
+
+    if [ ! -e "$CONF" ]; then
+      echo "open-bamboo-networking: $CONF doesn't exist yet, skipping" \
+           "(launch OrcaSlicer once first)"
+    else
+      NEEDS_PATCH=$(${pkgs.jq}/bin/jq -r --arg ver "${cfg.obnVersion}" '
+        (.app.installed_networking != "true")
+        or (.app.network_plugin_version != $ver)
+      ' "$CONF")
+
+      if [ "$NEEDS_PATCH" = "true" ]; then
+        if [ -n "''${DRY_RUN_CMD:-}" ]; then
+          echo "open-bamboo-networking: would patch $CONF (dry run)"
+        else
+          cp -f "$CONF" "$CONF.bak"
+          TMP=$(mktemp)
+          ${pkgs.jq}/bin/jq --arg ver "${cfg.obnVersion}" '
+            .app.installed_networking = "true"
+            | .app.network_plugin_version = $ver
+            | .app.network_plugin_remind_later = "true"
+          ' "$CONF" > "$TMP"
+          cat "$TMP" > "$CONF"
+          rm -f "$TMP"
+          echo "open-bamboo-networking: patched $CONF (backup: $CONF.bak)"
+        fi
+      fi
+    fi
+  '';
+}
+```
+
+## AI disclosure
+
+The Nix packaging in this repo was written with substantial AI assistance. It
+hasn't been reviewed by anyone but the repo maintainer's own testing - treat it
+accordingly and read through `package.nix`/`hm-module.nix` yourself before
+trusting it with your setup.