meshcore-packet-capture/NIXOS.md

NixOS Support

This project includes a NixOS service module that allows you to run MeshCore Packet Capture as a systemd service on NixOS.

Quick Start

Add this to your /etc/nixos/configuration.nix:

{
  imports = [
    (builtins.fetchTarball "https://github.com/agessaman/meshcore-packet-capture/archive/main.tar.gz")
  ];

  services.meshcore-packet-capture = {
    enable = true;
    connectionType = "ble";
    
    mqtt1 = {
      enabled = true;
      server = "mqtt.example.com";
      port = 1883;
      username = "your_username";
      password = "your_password";
    };
  };
}

Then rebuild your system:

sudo nixos-rebuild switch

Using with Flakes

If you're using Nix Flakes, add this to your flake.nix:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    meshcore-packet-capture = {
      url = "github:agessaman/meshcore-packet-capture";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { self, nixpkgs, meshcore-packet-capture }: {
    nixosConfigurations.your-hostname = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        meshcore-packet-capture.nixosModules.default
        {
          services.meshcore-packet-capture = {
            enable = true;
            package = meshcore-packet-capture.packages.${system}.default;
            # ... your configuration
          };
        }
      ];
    };
  };
}

Configuration Options

Connection Settings

services.meshcore-packet-capture = {
  connectionType = "ble";  # or "serial" or "tcp"
  bleAddress = "AA:BB:CC:DD:EE:FF";  # optional
  bleDeviceName = "MeshCore Device";  # optional
  serialPorts = [ "/dev/ttyUSB0" "/dev/ttyUSB1" ];  # for serial connection
  tcpHost = "localhost";  # for TCP connection
  tcpPort = 5000;  # for TCP connection
  timeout = 30;
  maxConnectionRetries = 5;  # 0 = infinite
  connectionRetryDelay = 5;
  healthCheckInterval = 30;
};

MQTT Brokers

You can configure up to 4 MQTT brokers:

services.meshcore-packet-capture = {
  mqtt1 = {
    enabled = true;
    server = "mqtt.example.com";
    port = 1883;
    username = "user";
    password = "pass";
    transport = "tcp";  # or "websockets"
    useTLS = true;
    tlsVerify = true;
    useAuthToken = false;
    tokenAudience = null;
    clientIdPrefix = null;
    qos = 0;
    retain = false;
    keepalive = 60;
    topicStatus = "meshcore/status";
    topicPackets = "meshcore/packets";
    topicRaw = "meshcore/raw";
    topicDecoded = "meshcore/decoded";
    topicDebug = "meshcore/debug";
  };
  
  # Similar configuration for mqtt2, mqtt3, mqtt4
};

Authentication

For username/password authentication:

services.meshcore-packet-capture = {
  mqtt1 = {
    username = "your_username";
    password = "your_password";
  };
};

For JWT token authentication:

services.meshcore-packet-capture = {
  mqtt1 = {
    useAuthToken = true;
    tokenAudience = "mqtt.example.com";
  };
  privateKey = "your_private_key_hex_string";
  # OR
  privateKeyFile = "/path/to/private/key/file";
};

Other Settings

services.meshcore-packet-capture = {
  logLevel = "INFO";  # DEBUG, INFO, WARNING, ERROR, CRITICAL
  verbose = false;
  debug = false;
  enableMqtt = true;
  maxMqttRetries = 5;  # 0 = infinite
  mqttRetryDelay = 5;
  exitOnReconnectFail = true;
  iata = "SEA";  # For topic templates
  origin = "My Device";
  advertIntervalHours = 11;  # 0 = disabled
  uploadPacketTypes = [ 0 1 2 ];  # Filter packet types, null = all
  rfDataTimeout = 15.0;
  outputFile = null;  # Optional output file path
  dataDir = "/var/lib/meshcore-packet-capture";
  user = "meshcore";
  group = "meshcore";
};

Permissions

The service automatically adds the service user to the bluetooth and dialout groups for BLE and serial port access.

Development

To enter a development shell with all dependencies:

nix develop

Troubleshooting

Package not found

If you get an error about meshcore package not being found, you may need to update the hash in nix/packages.nix. The first time you build, Nix will tell you the correct hash to use.

BLE not working

Ensure that:

1. Bluetooth is enabled: services.bluetooth.enable = true;
2. The service user has proper permissions (automatically handled)
3. Your Bluetooth adapter is properly configured

Serial port not accessible

Ensure that:

1. The device exists: ls -l /dev/ttyUSB0
2. The service user is in the dialout group (automatically handled)
3. You've specified the correct port in serialPorts

Service logs

View service logs with:

journalctl -u meshcore-packet-capture -f

Building the Package

To build just the package (without installing as a service):

nix build

The package will be available at ./result/bin/meshcore-packet-capture.