Playing it

Two minutes to your first delve, with nothing but a laptop. The radios come later, when you want company.

Going down alone needs no one to talk to, so it needs no radio either. That is the whole of the first half of this page. If you like it, the second half is how to bring people.

On your own, right now

  1. Check you have Python

    Open a terminal and type python3 --version. Anything numbered 3.9 or higher is fine.

    macOS
    Press Cmd+Space, type Terminal, press Enter. Python is already there.
    Linux
    Already there.
    Windows
    Press Start, type cmd. Use python --version. If nothing happens, install from python.org and tick Add Python to PATH during setup.

  2. Download the two folders

    catacomms is the game; loraline is the radio underneath it, and it is needed even when there is no radio, because it is what the game talks through.

    From the catacomms repository and the loraline one, click the green Code button on each, then Download ZIP. Unzip both next to each other, on the Desktop say.

    Now point the terminal at the game folder. Type cd with a space after it, drag the unzipped catacomms folder onto the terminal window, and press Enter.

  3. Install the two pieces

    pip3 install pyserial pynacl

    On Windows use pip rather than pip3, and run one extra line, because Windows does not ship the terminal interface Python needs:

    pip install windows-curses

    Then check the whole thing works, with no hardware and no radio:

    PYTHONPATH=../loraline python3 tests.py

    On Windows that line is two: set PYTHONPATH=..\loraline then python tests.py.

    You want a list of lines beginning ok, ending ALL PASS. That runs three players through a whole fight over a simulated lossy radio, so if it passes, everything except the actual radio is proven.

  4. Go down

    PYTHONPATH=../loraline python3 -m catacomms --nick yourname \
    --tcp-listen 4242 --web

    Open localhost:8080. Type /delve in the box, then /begin, and you are in a room with something that wants to eat you.

    Arrows or hjkl move. Hold shift, or HJKL, to strike. d sets down whatever you need least. Space waits. On a phone or tablet, tap a square next to you and it works out whether that is a step or a swing.

    The board for whatever this machine has witnessed is at localhost:8080/board, and keeps itself up to date. Going down alone does not put anything on it, because you cannot witness your own loot.

    What the flags do. --tcp-listen gives the client something to talk through and a door for a friend to arrive by later. --web serves the browser view. Leave --web off and it draws in the terminal instead, which works over SSH on anything.

With other people

Everyone needs their own radio. This is the part that makes it a different sort of game: your party is whoever your antenna can actually reach.

  1. Buy the radios

    One Waveshare USB-TO-LoRa-HF per person. Small, roughly the price of a takeaway each, plugs into a normal USB port, no firmware to flash.

    Watch the last two letters. HF covers 868 and 915 MHz, which is Europe, North America and Australia. LF is a different band for parts of Asia and cannot talk to an HF unit. Everyone needs the same variant. The TCXO version costs slightly more and is worth it.

    An antenna is included. Do not buy a better one yet.

  2. Set the frequency, before transmitting anything

    They arrive tuned to 868 MHz, the European band. Elsewhere that is somebody else's licensed spectrum.

    Where you areUse
    Europe, UK, Norway--band eu868
    United States, Canada--band us915
    Australia, New Zealand--band au915

    Find the port first: ls /dev/cu.* on macOS, ls /dev/ttyUSB* on Linux, Device Manager under Ports on Windows. Unplug it and look again; the entry that vanishes is yours. On macOS use cu. and never tty., which will simply hang.

    cd ../loraline
python3 -m loraline config --port /dev/ttyUSB0 --band eu868

    Every module in the group gets the same command.

    These presets cover the common cases. Power limits and duty cycles vary by country, and you are responsible for what your radio transmits. loraline's setup goes into it properly.

  3. Check the radios can hear each other

    Worth doing before anything else, because it is the one thing that can actually fail. At one end:

    python3 -m loraline link --port /dev/ttyUSB0 --band eu868 --role pong

    At the other:

    python3 -m loraline link --port /dev/ttyUSB0 --band eu868 --role ping

    You get signal strength and packet loss every few seconds. Across a room, expect around −40 dBm and nothing lost. Between houses, anything better than −110 is a comfortable link. Stand the antennas upright and near a window: height beats everything.

  4. Play together

    Agree a passphrase in person, not over the radio. Then everybody runs:

    export LORALINE_KEY="the phrase you all agreed"
cd catacomms
PYTHONPATH=../loraline python3 -m catacomms --port /dev/ttyUSB0 \
    --band eu868 --nick yourname --web

    On Windows, set LORALINE_KEY=the phrase you all agreed.

    Within a few seconds the others appear. One person types /delve, everyone else types /join, and the first person types /begin. Anything you type that is not a command is said out loud to the party, over the same radio, in the same window.

  5. Somebody far away

    A person with no radio can still join, by reaching someone who has one over the internet. Whoever holds a radio adds --tcp-listen 4242; the distant one runs no radio at all:

    PYTHONPATH=../loraline python3 -m catacomms --nick theirname \
    --tcp-connect your-address:4242 --web

    The people near you never touch the internet, the distant one never touches a radio, and everyone is in the same room. loraline's page covers how to give them an address to reach.

When something does not work

The tests fail before any hardware is involved
Almost always that loraline is not where catacomms expects. The two folders must sit next to each other, and PYTHONPATH=../loraline has to point at the outer folder, the one holding README.md.
No port appears
Try a different cable, then a different socket; some cables carry power only. On older Windows machines the module may need its CH340 or CP210x driver, which the manufacturer supplies.
Permission denied opening the port
Linux only: sudo usermod -aG dialout $USER, then log out of the computer completely and back in. A new terminal is not enough.
Every AT command replies "(no reply)"
Wrong port, or another program has the module open. Close any serial terminal or Arduino IDE and try again.
The link test sends but nothing comes back
The two modules disagree about something. Run the config command again on both with identical arguments.
They connect but nobody appears
Different passphrases. LORALINE_KEY must match exactly, capitals included.
Two clients on one computer ignore each other
They loaded the same keypair and decided they were the same person. Give the second one --identity ~/.loraline/second.
It works on the desk but not between houses
The expected problem, and it is about obstruction rather than distance. Antenna higher and nearer a window at both ends, then try --sf 12 on every module for maximum range at the cost of speed.