netTAK Voice Install Guide

netTAK Voice turns a Raspberry Pi with a Codec Zero audio HAT into a push-to-talk (PTT) radio endpoint on the netTAK network. It puts your netTAK nodes and your handsets on one push-to-talk net — the same Opus-over-multicast voice channels ATAK's voice plugin uses — so one netTAK talks to other netTAK nodes and to phones/tablets running ATAK's voice plugin, with no server and no internet.

The voice engine (nettak-voice) installs standalone — it does not touch a netTAK mesh/AP install, and the two can coexist on the same Pi or run on separate machines.

New to Linux / the Raspberry Pi? Follow the steps exactly in order. Every command is complete — you don't need to know where anything lives; copy and paste each line as-is. The only things you change are the values in <angle brackets> (your Pi's address and your login).

The install has three stages: (1) download the files to your computer, (2) copy them onto the Pi, (3) run the installer on the Pi.

1. What you need

A Raspberry Pi with a Raspberry Pi Codec Zero HAT, running Raspberry Pi OS 64-bit (Bookworm).
The Pi connected to your network (Ethernet recommended) and its IP address on that network.
The Pi's login — the username and password you set when imaging the card.
A PTT input wired to a GPIO line (default: GPIO 27, active-low) and a mic + speaker on the Codec Zero (line/AUX out).
ATAK with its voice plugin on the handsets you want to talk to.
A way to copy files to the Pi and to run commands on it:
Windows: WinSCP (free, for copying files — download from winscp.net) and PuTTY or Windows PowerShell (for running commands).
macOS / Linux: the built-in Terminal (uses scp and ssh).

2. Download the files (to your computer)

On the netTAK download page at activate.xtak.ai, download these to your computer (they'll land in your Downloads folder):

nettak-voice-install-*-arm64.tar.gz — the voice install bundle. It is fully offline: the GStreamer/Opus/gpiod packages are vendored inside, so no apt download is needed on the Pi.
SHA256SUMS*.txt — the checksum used to confirm the download is intact.

3. Copy the files onto the Pi

You're copying the downloaded files into the Pi's home folder.

Windows — WinSCP (recommended)

Install and open WinSCP.
In the login window: File protocol = SCP; Host name = your Pi's IP address; User name and Password = your Pi login. Click Login (accept the host-key prompt the first time).
WinSCP shows two panes — your computer on the left, the Pi on the right (it opens in the Pi's home folder).
On the left, go to your Downloads folder and drag the two downloaded files into the right pane. Wait for the copy to finish.

macOS / Linux — Terminal (`scp`)

Replace <user> and <pi-ip> with your Pi's login and IP:

scp ~/Downloads/nettak-voice-install-*-arm64.tar.gz ~/Downloads/SHA256SUMS*.txt <user>@<pi-ip>:~/

4. Connect to the Pi and verify the download

Open a command session on the Pi:

Windows: open PuTTY, enter the Pi's IP, and log in — or in PowerShell run ssh <user>@<pi-ip>.
macOS / Linux: in Terminal run ssh <user>@<pi-ip>.

Then, on the Pi, confirm the bundle copied over intact:

cd ~
sha256sum --ignore-missing -c ~/SHA256SUMS*.txt

It must print:

nettak-voice-install-*-arm64.tar.gz: OK

If it does not say OK, the copy was incomplete — delete it and copy it again (step 3):

rm ~/nettak-voice-install-*-arm64.tar.gz    # only if verification failed

Unpack the bundle (this creates the folder ~/nettak-voice-install-*-arm64/):

cd ~
tar xzf ~/nettak-voice-install-*-arm64.tar.gz

5. Install (on the Pi)

Run the installer from inside the unpacked folder:

cd ~/nettak-voice-install-*-arm64
sudo bash scripts/voice/install-voice.sh

The installer:

runs a GPL-plugin guard over the vendored debs, then installs them offline,
installs the nettak-voice binary to /opt/nettak-voice/bin/,
installs the known-good Codec Zero mixer profile (restored on every start),
collects license notices under /opt/nettak-voice/licenses/,
installs and enables + starts nettak-voice.service.

The installer preserves an existing /etc/nettak-voice/config, so re-running it to upgrade keeps your settings. Re-installing over a running service does not auto-restart it — run sudo systemctl restart nettak-voice to activate the new binary. The files you copied into your home folder are just the installer package, and can be deleted once the install finishes.

6. Configure

Engine settings — `/etc/nettak-voice/config`

Static, node-local settings (audio device, PTT line, mic/speaker levels). The defaults suit a standard Codec Zero + GPIO-27 PTT, so most installs need no changes here. To override a value, uncomment it:

VOICE_ALSA_DEVICE=plughw:CARD=Zero
VOICE_PTT_LINE=27
VOICE_PTT_ACTIVE_LOW=true

Channels — `/etc/nettak-voice/voice.json`

The channel table (name → multicast group + port) and this node's active channel. On a netTAK mesh node this file is written and gossiped automatically — you don't touch it. On a standalone voice node, place one manually, e.g.:

{
  "channels": [
    { "slot": 1, "name": "Alpha", "group": "239.9.9.9",  "port": 6100 },
    { "slot": 2, "name": "Bravo", "group": "239.9.9.10", "port": 6200 }
  ],
  "active_slot": 2
}

A channel change (edit the file then run sudo systemctl reload nettak-voice, or switch from the netTAK UI) retunes live — no restart, no dropped audio.

To talk to ATAK: set your ATAK voice-plugin endpoints to the same multicast group and port as this node's active channel.

7. Verify

Check the service is running, then read the engine's self-test:

systemctl is-active nettak-voice          # -> active
cat /run/nettak-voice/status.json         # the engine's self-test

A healthy engine reports (give it ~30 s after a restart to settle):

{"rx_up":true,"tx_up":true,"rx_joined_all_ifaces":true,
 "playback_open":true,"capture_open":true,"restarts_recent":0, ...}

Field	Means
`rx_up` / `tx_up`	The receive and transmit audio pipelines are running.
`rx_joined_all_ifaces`	Multicast is joined on every IP interface — voice reaches peers on any network segment the node is on.
`playback_open` / `capture_open`	The Codec Zero speaker and mic are open.

On a netTAK node, the admin Dashboard shows a Voice health chip driven by this same self-test (green / red-with-fault-name / stale). Finally, press the PTT button and confirm two-way audio with a handset running ATAK's voice plugin on the active channel.

8. Update or uninstall

Update: copy the newer bundle onto the Pi (steps 2–4) and re-run sudo bash scripts/voice/install-voice.sh, then sudo systemctl restart nettak-voice. Your config and channels are preserved.
Stop / disable: sudo systemctl disable --now nettak-voice.

netTAK Voice is a product of xTAK (Altay Corporation). Support & licensing: Support.

netTAK VoiceInstall Guide.