Configuration

Crow Configuration Reference

Crow is configured using two files located in /usr/local/crow:

• crow.conf — Default configuration (overwritten on updates)
• crow.conf.override — User overrides (preserved across updates) ⭐ Edit this file

Only modify crow.conf.override. If it doesn't exist, create it with minimal content:

{
}

All configuration blocks below are top-level keys added to this JSON file. Restart Crow to apply changes:

/etc/init.d/crow restart

---

Core Configuration

Callsign

Set your node's AREDN callsign:

{
  "callsign": "N0CALL-10"
}

---

Bridge Configurations

Crow can bridge messages between several transport families. Each bridge backend handles a different network type:

Bridge section	Backend config	Status	Transport	Purpose
MeshIP (AREDN) Bridge	meship	Default	MeshIP (native AREDN)	AREDN-to-AREDN mesh routing and client messaging
Meshtastic Bridge	meshtastic	Default	UDP/multicast	Bridge to Meshtastic devices on your LAN
MeshCore Bridge	meshcore, meshcore_tcp_api, meshcore_serial_api	Opt-in	UDP/TCP/USB serial	Bridge to MeshCore Companion devices
APRS Bridge	aprs	Optional	APRS-IS/KISS TCP	Amateur radio APRS network integration

---

MeshIP (AREDN) Bridge

Prerequisites: Crow is running on an AREDN node with MeshIP connectivity. No external hardware required; MeshIP is the native AREDN mesh transport.

Enable the bridge:

{
  "meship": {}
}

Client vs. Gateway Mode:

• Client mode (default): Messages from other AREDN nodes are received and displayed. Your node cannot forward messages between separate AREDN meshes.

  {
    "meship": {
      "bridge": false
    }
  }

• Gateway/Bridge mode: Your node forwards messages between connected AREDN meshes (if they are split or use multi-radio gateways).

  {
    "meship": {
      "bridge": true
    }
  }

Channel Binding: All channels automatically participate in MeshIP routing. You can bridge Meshtastic, MeshCore, and APRS traffic into AREDN channels using the channel configuration (see Channel Configuration).

---

Meshtastic Bridge

Prerequisites: Meshtastic device with Ethernet/LAN capability connected to your AREDN node's LAN interface. See Meshtastic for hardware and device setup.

Enable the bridge:

{
  "meshtastic": {}
}

Channel Configuration: Bind channels to Meshtastic by adding "meshtastic": true to channel entries in the channels array:

{
  "channels": [
    { "namekey": "AREDN og==", "telemetry": true },
    { "namekey": "LongFast AQ==", "telemetry": true, "meshtastic": true }
  ]
}

Note: Meshtastic uses multicast; no address configuration needed. Ensure your Meshtastic device's modem preset matches the Crow channel ID.

---

MeshCore Bridge

Crow supports three MeshCore transport choices. The Companion TCP and USB/serial paths share the same framed TX/RX implementation; only the transport changes.

TCP Companion API

Use this when the MeshCore device exposes its Companion API on the network, normally port 4403:

{
  "meshcore": { "backend": "tcp" },
  "meshcore_tcp_api": {
    "enabled": true,
    "host": "10.245.94.47",
    "port": 4403,
    "channel_discovery": true
  }
}

The host is the MeshCore device or Companion API bridge, not Crow's WebSocket port (4404). The default Companion TCP port is 4403.

USB serial Companion API

Use this when the MeshCore node is physically attached to the Crow host:

{
  "meshcore": { "backend": "serial" },
  "meshcore_serial_api": {
    "enabled": true,
    "device": "/dev/ttyACM0",
    "baud": 115200,
    "app_start_profile": "crow_zeros",
    "channel_discovery": true
  }
}

/dev/ttyUSB0 is also supported. meshcore_usb_api is accepted as an alias for meshcore_serial_api.

The USB path uses the binary Companion protocol directly. It is not a line-oriented CLI and Crow does not shell out to meshcore-cli.

Both Companion transports support receive and transmit. Crow sends channel text with Companion command 0x03 after resolving the MeshCore channel slot. Outbound direct text is deliberately not enabled yet because Crow does not mirror the radio's contact and path tables; direct messages can still be received by the connected radio.

Useful optional settings for both paths:

{
  "meshcore_tcp_api": {
    "max_pending_rx": 4,
    "channel_discovery": true,
    "channel_refresh_seconds": 600
  }
}

For USB serial, use the same fields under meshcore_serial_api.

Legacy UDP

The original UDP backend remains available with:

{
  "meshcore": { "backend": "udp" }
}

Set an explicit backend when more than one transport configuration is present. Without an explicit selector, TCP is preferred over serial, and serial is preferred over UDP only when TCP is not enabled.

Restart Crow after changing the configuration:

/etc/init.d/crow restart

---

APRS Bridge

⚠️ Important: APRS is public amateur-radio traffic. Encryption is prohibited under FCC Part 97. Keep tx_enabled disabled until you fully understand callsign, passcode, and operator control requirements.

Single Backend (APRS-IS, Dire Wolf, or Xastir)

{
  "callsign": "N0CALL-10",
  "aprs": {
    "enabled": true,
    "callsign": "N0CALL-10",
    "channel": "APRS og==",
    "default_group": "APRSgroup1",
    "inline_max_members": 10,
    "backend": {
      "type": "aprsis",
      "host": "rotate.aprs2.net",
      "port": 14580,
      "passcode": "-1",
      "tx_enabled": false
    },
    "groups": [
      {
        "name": "APRSgroup1",
        "members": ["N0CALL-4", "N0CALL-7"],
        "repeat_member_messages": false,
        "rate_limit_seconds": 20,
        "max_members": 10
      }
    ]
  },
  "channels": [
    { "namekey": "AREDN og==", "telemetry": false },
    { "namekey": "APRS og==", "telemetry": false }
  ]
}

Backend Types:

• aprsis — APRS-IS (recommended): host, port, passcode
• direwolf — Dire Wolf KISS-over-TCP: host, port
• xastir — Xastir/YAAC TCP text: host, port

Multi-Backend Configuration

Use backends (plural) to run multiple APRS connections simultaneously:

{
  "callsign": "N0CALL-10",
  "aprs": {
    "enabled": true,
    "callsign": "N0CALL-10",
    "channel": "APRS og==",
    "default_group": "APRSgroup1",
    "backends": {
      "primary": {
        "type": "aprsis",
        "host": "rotate.aprs2.net",
        "port": 14580,
        "passcode": "-1",
        "tx_enabled": false
      },
      "local": {
        "type": "direwolf",
        "host": "192.168.1.50",
        "port": 8000
      }
    },
    "groups": [
      {
        "name": "APRSgroup1",
        "members": ["N0CALL-4", "N0CALL-7"],
        "repeat_member_messages": false,
        "rate_limit_seconds": 20,
        "max_members": 10
      }
    ]
  },
  "channels": [
    { "namekey": "AREDN og==", "telemetry": false },
    { "namekey": "APRS og==", "telemetry": false }
  ]
}

APRS Channels: Always use the AREDN open key (og==) for APRS channels to comply with FCC Part 97 (no encryption).

Group Repeating: Enable repeat_member_messages to forward received messages from one group member to others (excluding the sender):

{
  "name": "APRSgroup1",
  "members": ["N0CALL-4", "N0CALL-7"],
  "repeat_member_messages": true,
  "rate_limit_seconds": 20,
  "max_members": 10
}

See APRS for detailed backend setup and troubleshooting.

---

Storage Configuration

USB Storage

Store Crow data on an external USB drive:

{
  "storage": {
    "mode": "usb",
    "mountpoint": "/mnt/crow",
    "label": "CROWDATA",
    "device": "/dev/sda1",
    "image_quota_mb": 64,
    "min_free_mb": 16
  }
}

Field	Default	Description
mode	internal	internal (node flash) or usb (external drive)
mountpoint	/mnt/crow	Where the USB drive is mounted
label	CROWDATA	Filesystem label (used when formatting)
device	auto-detect	Force a specific block device (e.g., /dev/sda1)
image_quota_mb	100	Max size for stored images (MB)
min_free_mb	16	Minimum free space before cleanup (MB)

See USB Storage for pre-configuration and device selection.

---

UI Configuration

Message Alignment

By default, messages you post appear on the right; others on the left. To align all messages to the left:

{
  "ui": {
    "message": {
      "align": "left"
    }
  }
}

Channel Key Format

Crow displays channel keys as base64 by default. To show hex encoding instead (useful for sharing with MeshCore users):

{
  "ui": {
    "key": {
      "format": "hex"
    }
  }
}

See UI Tweaks for additional customization options.

---

Complete Example

A realistic configuration combining multiple features, including experimental API backends:

{
  "callsign": "N0CALL-10",
  "meshtastic": {},
  "meship": {
    "bridge": false
  },
  "storage": {
    "mode": "usb",
    "device": "/dev/sda1"
  },
  "aprs": {
    "enabled": true,
    "callsign": "N0CALL-10",
    "channel": "APRS og==",
    "default_group": "APRSgroup1",
    "backends": {
      "primary": {
        "type": "aprsis",
        "host": "rotate.aprs2.net",
        "port": 14580,
        "passcode": "-1",
        "tx_enabled": false
      },
      "local": {
        "type": "direwolf",
        "host": "192.168.1.50",
        "port": 8000
      }
    },
    "groups": [
      {
        "name": "APRSgroup1",
        "members": ["N0CALL-4", "N0CALL-7"]
      }
    ]
  },
  "meshcore_tcp_api": {
    "enabled": true,
    "host": "192.168.1.100",
    "port": 4403,
    "channel_discovery": true,
    "channel_refresh_seconds": 300
  },
  "meshtastic_api": {
    "enabled": false,
    "device": "/dev/ttyACM0",
    "baud": 115200
  },
  "ui": {
    "message": {
      "align": "left"
    },
    "key": {
      "format": "hex"
    }
  },
  "channels": [
    { "namekey": "AREDN og==", "telemetry": true },
    { "namekey": "APRS og==", "telemetry": false, "meshtastic": true, "backend": "primary" },
    { "namekey": "LongFast AQ==", "telemetry": true, "meshtastic": true },
    { "namekey": "TacNet X2YZ", "telemetry": false }
  ]
}

Notes on the example:

• MeshIP (AREDN) bridge: The meship backend handles AREDN-to-AREDN MeshIP messaging. Set "bridge": false for client nodes (default); set "bridge": true for gateway/repeater nodes that forward between AREDN meshes.
• APRS multi-backend: The backends (plural) config shows both APRS-IS and local Dire Wolf. Channels can bind to a specific backend via "backend": "primary".
• MeshCore Companion API: Enabled with meshcore.backend plus meshcore_tcp_api or meshcore_serial_api. TCP uses port 4403; USB uses /dev/ttyACM0 or /dev/ttyUSB0. Channel discovery is enabled with channel_discovery.
• Meshtastic API (experimental): Set to false by default. Enable only if you want to test the experimental API backend instead of UDP multicast.
• Per-channel backend binding: Channels can specify which APRS backend to use via the "backend" field. If omitted, the default (first defined) is used.
• Channel telemetry: Set to false for APRS channels (FCC Part 97 compliance); true for mesh/AREDN channels to collect air-quality and environmental data.

---

Restart Crow

After editing crow.conf.override, always restart the service:

/etc/init.d/crow restart

---

Per-Channel Access Control

When Strict Gatekeeper is enabled, channels can enforce their own callsign allow/deny rules. Add an access_control block to individual channel entries:

{
  "channels": [
    {
      "namekey": "#TacNet base64key==",
      "access_control": {
        "require_callsign": true,
        "allowed_callsigns": ["K6*", "W2*"],
        "deny_callsigns": []
      }
    },
    {
      "namekey": "#OpenNet base64key==",
      "access_control": {
        "require_callsign": false
      }
    }
  ]
}

See Strict Gatekeeper — Per-Channel Access Control for pattern syntax and enforcement details.

---

MeshCore Discovery

When running a MeshCore Companion API backend, Crow can auto-discover group channels programmed into the radio's slots. Enable periodic discovery sync:

{
  "meshcore_tcp_api": {
    "enabled": true,
    "host": "127.0.0.1",
    "port": 4403,
    "channel_discovery": true,
    "channel_refresh_seconds": 300
  }
}

For USB serial, use the same discovery fields under meshcore_serial_api.

Field	Type	Default	Description
enabled	boolean	false	Enable group discovery and periodic sync.
channel_refresh_seconds	integer	300	How often (seconds) to re-query radio slots for changes.

Discovered groups appear in /cmd discover and can be joined with /join.

---

---

Raven Configuration Import

If you are upgrading from Raven to Crow, configuration and runtime data can be automatically imported on first boot.

What Gets Imported

The Raven-to-Crow migration script (crow-migrate-raven.sh) is a one-time compatibility importer that runs when Crow files do not exist. It preserves your:

• Callsign and location
• Channel definitions (with preserved keys and encryption settings)
• APRS/Meshtastic/MeshCore bridge config (with automatic schema updates)
• Storage configuration (USB device paths and quotas)
• Telemetry settings
• UI preferences (message alignment, key format, etc.)
• Strict Gatekeeper rules and access control lists
• Message history and node databases

How It Works

1. On first Crow boot, the system checks for legacy Raven config at:

   • /etc/raven.conf
   • /etc/raven.conf.override
   • /var/crow/... (runtime data)

2. If these files exist and Crow files do not, the importer:

   • Merges Raven's user-facing settings into Crow's default config
   • Validates each key — unknown or deprecated settings are skipped
   • Does NOT blindly copy entire config files (schema safety)
   • Imports message history, node databases, and textstore from Raven runtime paths

3. After import, Crow uses its own paths:

   • /etc/crow.conf (default, auto-updated)
   • /etc/crow.conf.override (your edits, preserved across updates)
   • /usr/local/crow/... (code)

Safe Keys

The following top-level config keys are considered stable and safe to import:

debug, role, callsign, location, messages, channels,
storage, telemetry, ui, aprs, meshtastic, meshcore, meship,
arednmesh, websocket, platform_aredn, platform_debian

Any other keys in your old Raven config are intentionally ignored to prevent schema conflicts or deprecated settings from blocking Crow startup.

If You Have Both Crow and Raven Config

• Crow config wins. If /etc/crow.conf.override exists, the importer does not run—your Crow config is already configured.
• Manual merge: If you want to selectively re-import from Raven, manually copy the relevant keys from /etc/raven.conf.override into /etc/crow.conf.override, then restart Crow.

Troubleshooting Import Issues

If import fails or you get unexpected config:

1. Check the startup log:

   logread | grep crow-migrate

2. Inspect the merged config:

   cat /etc/crow.conf.override

3. If needed, manually edit /etc/crow.conf.override and restart:

   /etc/init.d/crow restart

Do NOT Import From Raven If:

• You are running a fresh install with no prior Raven config (import will not run)
• You want a clean slate — delete Raven config files before Crow starts
• You have custom backend code in Raven that is not compatible with Crow's schema

---

Related Topics

• Meshtastic Bridge Setup
• MeshCore Bridge Setup
• APRS Bridge Setup
• Strict Gatekeeper
• USB Storage Setup
• UI Customization
• Channel Configuration