From 64364bec5df7c0901f32dec62ff534fa2b29631a Mon Sep 17 00:00:00 2001
From: Thiago Kenji Okada <thiagokokada@gmail.com>
Date: Sun, 19 Jul 2026 22:57:37 +0100
Subject: [PATCH] feat: add Nix development shell (#2645)

---
 README.md       | 18 +++++++++++
 nix/default.nix |  1 +
 nix/flake.lock  | 43 +++++++++++++++++++++++++++
 nix/flake.nix   | 79 +++++++++++++++++++++++++++++++++++++++++++++++++
 nix/shell.nix   | 12 ++++++++
 5 files changed, 153 insertions(+)
 create mode 120000 nix/default.nix
 create mode 100644 nix/flake.lock
 create mode 100644 nix/flake.nix
 create mode 100644 nix/shell.nix

diff --git a/README.md b/README.md
index 0287645d..7038a3df 100644
--- a/README.md
+++ b/README.md
@@ -158,6 +158,24 @@ cd crosspoint-reader
 git submodule update --init --recursive
 ```
 
+### Nix/NixOS
+
+Nix/NixOS users can enter the development shell with either `nix develop` (flakes) or `nix-shell`:
+
+```bash
+nix develop -f nix
+# or
+nix-shell nix
+```
+
+To flash a connected ESP32-C3 device, enable PlatformIO's udev rules in your NixOS configuration:
+
+```nix
+services.udev.packages = with pkgs; [ platformio-core.udev ];
+```
+
+After rebuilding the system configuration, reconnect the device or reload udev rules.
+
 ### Build / flash / monitor
 
 ```bash
diff --git a/nix/default.nix b/nix/default.nix
new file mode 120000
index 00000000..593a000b
--- /dev/null
+++ b/nix/default.nix
@@ -0,0 +1 @@
+shell.nix
\ No newline at end of file
diff --git a/nix/flake.lock b/nix/flake.lock
new file mode 100644
index 00000000..2d51f2ec
--- /dev/null
+++ b/nix/flake.lock
@@ -0,0 +1,43 @@
+{
+  "nodes": {
+    "flake-compat": {
+      "locked": {
+        "lastModified": 1767039857,
+        "narHash": "sha256-vNpUSpF5Nuw8xvDLj2KCwwksIbjua2LZCqhV1LNRDns=",
+        "owner": "NixOS",
+        "repo": "flake-compat",
+        "rev": "5edf11c44bc78a0d334f6334cdaf7d60d732daab",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1784356753,
+        "narHash": "sha256-12KrbMiWLcf8m7pCvAtZh1ZrgF85ZXDXvfR/fWTKy84=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "61b7c44c4073f0b827768aff0049561b5110ea5a",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-compat": "flake-compat",
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}
diff --git a/nix/flake.nix b/nix/flake.nix
new file mode 100644
index 00000000..08ad390d
--- /dev/null
+++ b/nix/flake.nix
@@ -0,0 +1,79 @@
+{
+  description = "CrossPoint Reader development environment";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    flake-compat.url = "github:NixOS/flake-compat";
+  };
+
+  outputs =
+    { nixpkgs, ... }:
+    let
+      systems = [
+        "x86_64-linux"
+        "aarch64-linux"
+      ];
+      forAllSystems = nixpkgs.lib.genAttrs systems;
+    in
+    {
+      devShells = forAllSystems (
+        system:
+        let
+          pkgs = import nixpkgs { inherit system; };
+          # Detect the project root from wherever the user entered the shell,
+          # so commands work from the repository root or any subdirectory.
+          # Using `git rev-parse` to do so (assuming git is installed
+          # system-wide); user can overwrite this by setting PROJECT_ROOT env.
+          setEnvs = ''
+            PROJECT_ROOT="''${PROJECT_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+            export PROJECT_ROOT
+            export PLATFORMIO_CORE_DIR="$PROJECT_ROOT/.cache/platformio"
+          '';
+          fhsEnv = pkgs.buildFHSEnv {
+            name = "crosspoint-reader-shell";
+
+            targetPkgs =
+              pkgs: with pkgs; [
+                python3
+                uv
+
+                # Runtime libraries used by PlatformIO's downloaded ESP32 toolchain binaries.
+                stdenv.cc.cc.lib
+                zlib
+                ncurses
+              ];
+
+            profile = ''
+              ${setEnvs}
+              export PATH="$PROJECT_ROOT/.venv/bin:$PATH"
+
+              if [ ! -x "$PROJECT_ROOT/.venv/bin/pio" ]; then
+                echo "Creating .venv and installing pioarduino PlatformIO Core..."
+                # Forcing python3 from fhsEnv, otherwise we get the following
+                # exception while running `pip check`
+                # ModuleNotFoundError: No module named 'littlefs'
+                uv venv --python /usr/bin/python3 "$PROJECT_ROOT/.venv" &&
+                uv pip install --python "$PROJECT_ROOT/.venv/bin/python" \
+                  -U https://github.com/pioarduino/platformio-core/archive/refs/tags/v6.1.19.zip \
+                  -r "$PROJECT_ROOT/requirements.txt" ||
+                echo "Failed to install pioarduino PlatformIO Core" >&2
+              fi
+            '';
+          };
+          pio = pkgs.writeShellScriptBin "pio" ''
+            exec ${fhsEnv}/bin/crosspoint-reader-shell -c 'exec pio "$@"' pio "$@"
+          '';
+        in
+        {
+          default = pkgs.mkShell {
+            packages = [
+              pio
+              fhsEnv
+            ];
+
+            shellHook = setEnvs;
+          };
+        }
+      );
+    };
+}
diff --git a/nix/shell.nix b/nix/shell.nix
new file mode 100644
index 00000000..692cd4df
--- /dev/null
+++ b/nix/shell.nix
@@ -0,0 +1,12 @@
+(import (
+  let
+    lock = builtins.fromJSON (builtins.readFile ./flake.lock);
+    nodeName = lock.nodes.root.inputs.flake-compat;
+  in
+  fetchTarball {
+    url =
+      lock.nodes.${nodeName}.locked.url
+        or "https://github.com/NixOS/flake-compat/archive/${lock.nodes.${nodeName}.locked.rev}.tar.gz";
+    sha256 = lock.nodes.${nodeName}.locked.narHash;
+  }
+) { src = ./.; }).shellNix