Skip to content

Installation

Fin edited this page Nov 14, 2026 · 3 revisions

Setup

This covers full installation, you can get more details about each stage in their respective wiki pages.

1. A supported wireless chipset/adapter

lspci -k | grep -A3 -i network      # what card is this?
iw list | grep -A8 'Supported interface modes'

You ideally want an adapter that supports Active monitor mode, look for "monitor" in "Supported interface modes." if you see it, then your adapter might work. If not present, your adapter might still be compatible with Mixed mode.

See HARDWARE.md to identify if your adapter is compatible.

2. Tool dependencies

Python 3.10 or newer, with iw and ip:

sudo apt install python3 iw iproute2          # Debian / Ubuntu
sudo dnf install python3 iw iproute           # Fedora
sudo pacman -S python iw iproute2             # Arch

No Python packages are required. If you want to use the GUI, install PyGObject from your distribution and skip pip, because it needs GTK 4 and libadwaita too:

sudo apt install python3-gi gir1.2-gtk-4.0 gir1.2-adw-1          # Debian / Ubuntu
sudo dnf install python3-gobject gtk4 libadwaita                 # Fedora
sudo pacman -S python-gobject gtk4 libadwaita                    # Arch

3. Your keys

Tuxchange doesn't come with any and will not run without them. From your own console:

  1. Dump aes_keys.txt with GodMode9 and copy it to ~/.config/tuxchange/aes_keys.txt.
  2. Extract the two binary constants from dumps you took yourself:
python3 tools/lp_extract_keys.py --cecd /path/to/cecd/code.bin \
                                 --cec-store /path/to/CEC-partition.bin

Check what it found:

python3 tools/lp_extract_keys.py

The wiki page Getting your keys explains how to dump these files and what they are used for.

4. Install

sudo ./install/install.sh install

The installer does the following:

  • copies the code to /opt/tuxchange
  • creates the store in /var/lib/tuxchange
  • copies your keys to /etc/tuxchange
  • writes /etc/systemd/system/tuxchange.service and /etc/default/tuxchange for the tunables
  • writes a polkit rule letting your desktop user start, stop and restart that one unit
  • adds a menu entry for the GUI

It enables the daemon but does not start it. Start it with:

sudo systemctl start tuxchange
journalctl -u tuxchange -f

The service runs as root, so it only runs root owned code. Re-run the installer after updating your clone of Tuxchange. Your existing key copies are left alone, so copy new ones to /etc/tuxchange yourself if you want to upload new ones.

sudo ./install/install.sh uninstall removes the unit, the polkit rule, the menu entry and /opt/tuxchange. It leaves your keys, your settings and your store alone.

5. First StreetPass

Power-on a 3DS, make sure StreetPass is on for at least one title, and walk it past the computer. Watch the log and 3DS notification LED to blink green. More than one attempt is normal, so give it a few minutes before deciding something is broken.

For faster results, forget your Wi-Fi network from System Settings and put the 3DS in sleep mode.

See First StreetPass for more details.

Running without installing

sudo ./scripts/tuxchange

Tunables

Edit /etc/default/tuxchange, then sudo systemctl restart tuxchange.

Variable Default Meaning
SP_IFACE (empty) The real wireless interface. Empty picks the first ath9k adapter. Any other driver must be named here.
SP_MON mon0 The monitor interface to create.
SP_STORE /var/lib/tuxchange Where received messages are kept. Must be a directory only root can change.
SP_CHANNELS 1,6,11 The channels to watch.
SP_WINDOW 180 Seconds of radio time per pass.
SP_IDLE 2 Seconds to pause between passes.
SP_ROTATE 0 Identity rotation period in seconds. 0 never rotates.
SP_EXTRA (empty) Extra arguments passed straight to sp_relay.py run.

The GUI and sp_relay.py ctl save the adapter and rotation period to /var/lib/tuxchange/relay.env, which overrides this file.

Changing the store path

The store path keeps logs, captures and CEC (StreetPass) data.

The installer builds the GUI's menu entry from the SP_STORE value in /etc/default/tuxchange. If you point the daemon at a different store, re-run the installer afterwards:

sudo nano /etc/default/tuxchange        # set SP_STORE
sudo ./install/install.sh install       # keeps your settings, regenerates the menu entry
sudo systemctl restart tuxchange

Without the second step the GUI opens one store while the daemon uses another, and appears empty. Re-running the installer is safe, because it never overwrites /etc/default/tuxchange once it exists. It refuses a store path that a non-root user could change.

The address Tuxchange transmits from is derived from the store path, so moving the store gives this machine a new identity. That gets you past a console's MAC filter, and it also means consoles no longer recognise you, making you seem as a new console (or Mii in Mii Plaza).

Clone this wiki locally