Add .gitignore entries for IDE and project-specific files

.editorconfig

@@ -0,0 +1,9 @@
+# EditorConfig for Rust template
+root = false
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true

.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,13 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="PyUnresolvedReferencesInspection" enabled="true" level="WARNING" enabled_by_default="true">
+      <option name="ignoredIdentifiers">
+        <list>
+          <option value="neopixel" />
+          <option value="board" />
+        </list>
+      </option>
+    </inspection_tool>
+  </profile>
+</component>

.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/rusty_dog.iml" filepath="$PROJECT_DIR$/.idea/rusty_dog.iml" />
+    </modules>
+  </component>
+</project>

.idea/rusty_dog.iml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="EMPTY_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/src" isTestSource="false" />
+      <sourceFolder url="file://$MODULE_DIR$/tests" isTestSource="true" />
+      <excludeFolder url="file://$MODULE_DIR$/target" />
+    </content>
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files

CONTRIBUTING.md

@@ -0,0 +1,9 @@
+# Contributing
+
+Thank you for considering contributing!
+
+- Please follow the project coding style and directory structure.
+- Submit issues or pull requests for bugs, features, or improvements.
+- Add tests for new features where possible.
+- Ensure your code builds and passes tests before submitting.
+- Contributions are licensed under CC BY-SA 4.0.

Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "rusty-dog"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+embassy-executor = { version = "0.7.0", features = ["task-arena-size-32768", "arch-cortex-m", "executor-thread", "executor-interrupt"] }
+embassy-time = { version = "0.4.0", features = ["generic-queue-8"] }
+embassy-rp = { version = "0.3.0", features = ["defmt", "unstable-pac", "time-driver", "critical-section-impl"] }
+embassy-net = { version = "0.6.0", features = ["defmt", "tcp", "udp", "dhcpv4", "medium-ethernet"] }
+embassy-sync = { version = "0.6.1" }
+embassy-usb = { version = "0.4.0" }
+cyw43 = { version = "0.3.0", features = ["defmt", "firmware-logs"] }
+cyw43-pio = { version = "0.3.0", features = ["defmt"] }
+
+cortex-m = "0.7.7"
+cortex-m-rt = "0.7.5"
+panic-probe = { version = "0.3.2", features = ["print-defmt"] }
+defmt = "0.3.10"
+defmt-rtt = "0.4.1"
+static_cell = "2.1.0"
+portable-atomic = { version = "1.11.0", features = ["critical-section"] }

LICENSE

@@ -0,0 +1,17 @@
+Creative Commons Attribution-ShareAlike 4.0 International
+
+<https://creativecommons.org/licenses/by-sa/4.0/>
+
+You are free to:
+
+- Share — copy and redistribute the material in any medium or format
+- Adapt — remix, transform, and build upon the material for any purpose, even commercially.
+
+Under the following terms:
+
+- Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made.
+- ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.
+
+No additional restrictions — You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.
+
+See the full license at the link above.

Makefile

@@ -0,0 +1,19 @@
+build:
+	cargo build
+
+run:
+	cargo run
+
+test:
+	cargo test
+
+clean:
+	cargo clean
+
+.PHONY: build run test clean
+
+
+# Flatpak build target
+.PHONY: flatpak-build
+flatpak-build:
+	flatpak-builder --force-clean build-flatpak flatpak/app.flatpak.json

README.md

@@ -0,0 +1,167 @@
+# Rusty Dog - Pico W Embedded Rust
+
+This project is an embedded Rust application for the Raspberry Pi Pico W, utilizing the Embassy async framework.
+
+## LLM Agent Guidelines
+
+This project uses LLM agents for configuration and housekeeping. Please refer to [agents.md](agents.md) for the rules and guidelines governing their use.
+
+## Quick Start
+
+```sh
+nix develop
+# or with direnv:
+direnv allow
+```
+
+### Automatic Environment Setup
+
+When you enter the devShell (via `direnv allow` or `nix develop`), the following happens automatically:
+
+✓ **Git Repository**: Initializes `.git` if not present
+✓ **Rust Targets**: Automatically adds common embedded Rust targets (ARM Cortex-M, RISC-V)
+✓ **Cargo Paths**: Sets up `$HOME/.cargo/bin` in PATH for cargo-installed binaries
+✓ **Welcome Banner**: Displays available tools and quick commands
+
+No manual setup needed! Just start coding.
+
+## Quickstart
+
+```sh
+nix flake init -t path:../flakes#rust
+nix develop
+cargo build
+```
+
+## Embedded Rust Support
+
+The devShell automatically installs common embedded Rust targets via `rustup`:
+
+| Target | Platform | Use Case |
+|--------|----------|----------|
+| `thumbv6m-none-eabi` | ARM Cortex-M0/M0+ | RP2040 (Pico) |
+| `thumbv7em-none-eabihf` | ARM Cortex-M4F/M7F | STM32, nRF52840 |
+| `riscv32imc-unknown-none-elf` | RISC-V 32-bit | ESP32-C3 (basic) |
+| `riscv32imac-unknown-none-elf` | RISC-V 32-bit (atomic) | ESP32-C3 (advanced) |
+
+**Note:** ESP32 Xtensa targets require espup or custom toolchains (see [esp-rs](https://github.com/esp-rs)).
+
+## Flatpak Packaging
+
+This template supports building Flatpak packages for your Rust application.
+
+### Build Flatpak Package
+
+1. Ensure you have `flatpak-builder` installed.
+2. Run:
+
+  ```bash
+  make flatpak-build
+  ```
+
+This will use the manifest at `flatpak/app.flatpak.json` to build a Flatpak bundle in the `build-flatpak/` directory.
+
+### Customize Manifest
+
+Edit `flatpak/app.flatpak.json` to update app ID, runtime, build commands, or sources as needed for your project.
+
+### Install/Run Flatpak Locally
+
+You can install and run the built Flatpak locally:
+
+```bash
+flatpak install --user build-flatpak/org.example.rustdevshell.flatpak
+flatpak run org.example.rustdevshell
+```
+
+## Included Tools
+
+| Tool | Purpose |
+|------|---------|
+| **cargo** | Rust package manager and build system |
+| **rustc** | Rust compiler |
+| **clippy** | Rust linter for catching common mistakes |
+| **rustfmt** | Rust code formatter |
+| **rust-analyzer** | Language server for IDE integration |
+| **rust-src** | Rust source code (for tools like rust-analyzer) |
+| **probe-rs** | Embedded debugger/flasher for ARM targets |
+| **espflash** | Flashing tool for ESP32 boards |
+| **openocd** | JTAG/SWD debugger for ARM and other targets |
+| **minicom** | Serial terminal for device output |
+| **elf2uf2-rs** | Convert ELF to UF2 format (RP2040) |
+| **picotool** | Pico-specific firmware operations |
+| **avrdude** | AVR microcontroller programmer |
+| **ravedude** | Rapid AVR development utility |
+
+## Testing & Development Features
+
+Build and testing tools:
+
+- **cargo test** - Run unit and integration tests
+- **cargo clippy** - Lint code for common issues
+- **cargo fmt** - Format code consistently with rustfmt
+
+**Example usage:**
+
+```bash
+# Run tests
+cargo test
+
+# Check code with clippy
+cargo clippy
+
+# Format code
+cargo fmt
+
+# Build for embedded target
+cargo build --target thumbv7em-none-eabihf --release
+```
+
+## Project Layout
+
+```
+Cargo.toml
+Cargo.lock
+src/
+  └── main.rs (or lib.rs)
+Makefile
+.envrc
+flake.nix
+```
+
+## Legacy Usage
+
+If you do not use flakes, run:
+
+```sh
+nix-shell
+```
+
+## Project Metadata
+
+See project.toml for example metadata.
+
+## Helper Tools
+
+- **`nix run .#dev-helper`** - Display tool versions and availability
+- **`cargo build`** - Build the project
+- **`cargo check`** - Quick syntax check without building
+- **`cargo doc --open`** - Generate and view documentation
+
+## Packaging for nixpkgs
+
+This template is structured for easy packaging in nixpkgs:
+
+- All sources in `src/`
+- `flake.nix` provides a devShell and template
+- Add a `default.nix` or package expression as needed for nixpkgs
+
+See [nixpkgs Rust packaging docs](https://nixos.org/manual/nixpkgs/stable/#rust) for more details.
+
+## Customization
+
+Edit `flake.nix` to:
+
+- Add additional Rust targets via `rustup target add [target]`
+- Include additional cargo plugins
+- Add board-specific tools (e.g., stm32cube, nrfjprog)

agents.md

@@ -0,0 +1,11 @@
+# LLM Agent Guidelines
+
+LLM agents and autonomous programmers are subject to the following rules:
+
+- **Executable Code**: Do NOT modify or write executable code (e.g., `.rs` files).
+- **Configuration & Housekeeping**: You ARE allowed to manage and modify:
+    - Nix configuration files (`flake.nix`, `default.nix`, `shell.nix`, etc.).
+    - Cargo configuration (`Cargo.toml`).
+    - Project housekeeping files (`.gitignore`, `.run/*.xml`, etc.).
+    - Project layout and file organization.
+- **Code Assistance**: If asked for code help, do NOT provide example code. Provide explanations of how to approach the task and link to primary sources (e.g., [The Rust Programming Language](https://doc.rust-lang.org/book/)).

default.nix

@@ -0,0 +1,29 @@
+{ pkgs }:
+let
+  lib = pkgs.lib;
+  templateName = builtins.baseNameOf (toString ./.);
+in
+{
+  ${templateName} = pkgs.stdenvNoCC.mkDerivation {
+    pname = templateName;
+    version = "0.1.0";
+    src = ./.;
+    dontBuild = true;
+    installPhase = ''
+      mkdir -p $out/share/${templateName}
+      if [ -d src ]; then
+        cp -r src $out/share/${templateName}/
+      fi
+      for f in README.md project.toml flake.nix default.nix shell.nix Makefile .editorconfig .gitignore; do
+        if [ -f "$f" ]; then
+          cp "$f" $out/share/${templateName}/
+        fi
+      done
+    '';
+    meta = with lib; {
+      description = "Template project: ${templateName}";
+      license = licenses.unfreeRedistributable;
+      platforms = platforms.all;
+    };
+  };
+}

flake.nix

@@ -0,0 +1,155 @@
+{
+  description = "A Nix-flake-based Rust development environment";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    fenix = {
+      url = "github:nix-community/fenix";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+
+  outputs =
+    inputs@{ self, ... }:
+    let
+      supportedSystems = [
+        "x86_64-linux"
+        "aarch64-linux"
+        "x86_64-darwin"
+        "aarch64-darwin"
+      ];
+      forEachSupportedSystem =
+        f:
+        inputs.nixpkgs.lib.genAttrs supportedSystems (
+          system:
+          f {
+            pkgs = import inputs.nixpkgs {
+              inherit system;
+              overlays = [
+                inputs.self.overlays.default
+              ];
+            };
+          }
+        );
+    in
+    {
+      templates = {
+        default = {
+          path = ./.;
+          description = "Rust dev environment using fenix; includes a skeletal Cargo project and packaged helper app";
+        };
+      };
+
+      overlays.default = _final: prev: {
+        rustToolchain =
+          with inputs.fenix.packages.${prev.stdenv.hostPlatform.system};
+          combine (
+            with stable;
+            [
+              clippy
+              rustc
+              cargo
+              rustfmt
+              rust-src
+            ]
+          );
+      };
+
+      devShells = forEachSupportedSystem (
+        { pkgs }:
+        {
+          default = pkgs.mkShell {
+            packages = with pkgs; [
+              rustToolchain
+              git
+              gnumake
+              openssl
+              pkg-config
+              cargo-deny
+              cargo-edit
+              cargo-watch
+              cargo-generate
+              rust-analyzer
+              rustup
+              # Embedded Rust tooling
+              probe-rs-tools
+              espflash
+              openocd
+              minicom
+              # RP2040 UF2 workflows
+              elf2uf2-rs
+              picotool
+              avrdude
+              pkgsCross.avr.buildPackages.libc
+              pkgsCross.avr.buildPackages.gcc
+              ravedude
+              pre-commit
+            ];
+
+            env = {
+              # Required by rust-analyzer
+              RUST_SRC_PATH = "${pkgs.rustToolchain}/lib/rustlib/src/rust/library";
+            };
+
+            shellHook = ''
+              # Initialize git repository if not already present
+              if [ ! -d .git ]; then
+                git init
+                echo "✓ Initialized git repository"
+              fi
+
+              # Ensure user's Cargo-installed binaries are available
+              export PATH="$HOME/.cargo/bin:$PATH"
+
+              if command -v rustup >/dev/null 2>&1; then
+                echo "Ensuring common embedded Rust targets are available (idempotent)..."
+                rustup target add thumbv6m-none-eabi       >/dev/null 2>&1 || true  # Cortex-M0/M0+ (RP2040)
+                rustup target add thumbv7em-none-eabihf    >/dev/null 2>&1 || true  # Cortex-M4F/M7F (many STM32/nRF52)
+                rustup target add riscv32imc-unknown-none-elf >/dev/null 2>&1 || true
+                rustup target add riscv32imac-unknown-none-elf >/dev/null 2>&1 || true  # ESP32-C3 class
+                echo "Note: ESP32 Xtensa targets require espup/custom toolchains (see esp-rs)."
+              fi
+              echo "[rust-template] Welcome to the Rust dev shell!"
+              echo "Tools: cargo, rustc, clippy, rustfmt, rust-analyzer, probe-rs, espflash, openocd, minicom, elf2uf2-rs, picotool, avrdude, ravedude"
+              echo "Run 'cargo build' to build, or 'nix run .#dev-helper' for a tool summary."
+              echo "See README.md for usage."
+            '';
+          };
+        }
+      );
+
+      packages = forEachSupportedSystem (
+        { pkgs }:
+        {
+          # Build the skeletal Cargo project
+          default = pkgs.rustPlatform.buildRustPackage {
+            pname = "rusty-dog";
+            version = "0.1.0";
+            src = ./.;
+            cargoLock.lockFile = ./Cargo.lock;
+          };
+
+          devHelper = pkgs.writeShellScriptBin "dev-helper" ''
+            echo "Rust toolchain available:"
+            command -v cargo >/dev/null 2>&1 && cargo --version || true
+            command -v rustc >/dev/null 2>&1 && rustc --version || true
+            echo "This binary is built by Nix (packages.default)."
+          '';
+        }
+      );
+
+      apps = forEachSupportedSystem (
+        { pkgs }:
+        {
+          default = {
+            type = "app";
+            program = pkgs.lib.getExe self.packages.${pkgs.stdenv.hostPlatform.system}.default;
+          };
+          dev-helper = {
+            type = "app";
+            program = pkgs.lib.getExe self.packages.${pkgs.stdenv.hostPlatform.system}.devHelper;
+          };
+        }
+      );
+    };
+}

flatpak/app.flatpak.json

@@ -0,0 +1,22 @@
+{
+    "app-id": "org.example.rustdevshell",
+    "runtime": "org.freedesktop.Platform",
+    "runtime-version": "23.08",
+    "sdk": "org.freedesktop.Sdk",
+    "command": "rustdevshell-app",
+    "modules": [
+        {
+            "name": "rustdevshell-app",
+            "buildsystem": "simple",
+            "build-commands": [
+                "cargo build --release"
+            ],
+            "sources": [
+                {
+                    "type": "dir",
+                    "path": "../src"
+                }
+            ]
+        }
+    ]
+}

project.toml

@@ -0,0 +1,6 @@
+[project]
+name = "rust-template"
+description = "A reusable Nix flake template for Rust development."
+version = "0.1.0"
+authors = ["gooba42 <your@email>"]
+license = "MIT"

shell.nix

@@ -0,0 +1,15 @@
+{
+  pkgs ? import <nixpkgs> { },
+}:
+pkgs.mkShell {
+  buildInputs = [
+    pkgs.rustc
+    pkgs.cargo
+    pkgs.rustfmt
+    pkgs.clippy
+    pkgs.rust-analyzer
+  ];
+  shellHook = ''
+    echo "[shell.nix] Legacy shell for Rust dev. Use 'nix develop' for full flake support."
+  '';
+}

src/main.rs

@@ -0,0 +1,3 @@
+fn main() {
+    println!("Hello from Rust skeletal app. Edit src/main.rs to get started!");
+}

tests/sample_test.rs

@@ -0,0 +1,4 @@
+#[test]
+fn test_sample() {
+    assert_eq!(1, 1);
+}