Playing it

Going down alone needs nobody to talk to, so it needs no radio. That is the first half of this page. The second half is how to bring people.

The short way

Download the loraline app. catacomms is inside it: open the app, and there is a switcher across the top with catacomms on it. Nothing else to install, and the chat is the same conversation the party talks in.

What follows is the same thing from source, which is worth doing if you want to change it.

From source

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 is needed even without a 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 lines beginning ok, ending ALL PASS. That runs three players through a whole fight over a simulated lossy radio, so everything but the radio itself 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.

   /delve 3 2 goes to depth three carrying two torches, if you have cut any. /camp goes above ground to cut some: press c and then a direction, and x when you are done. /stash shows what you can prove you own.

   Arrows or hjkl move. Hold shift, or HJKL, to strike. d sets down whatever you need least. Space waits, which means waiting until something happens rather than for one tick. On a phone or tablet, tap a square next to you and it works out whether that is a step or a swing.

   Cutting a tree takes a minute of game time and one frame of radio. A swing costs the same frame as a chop, so fighting is expensive and working is nearly free.

   The sidebar shows your pack, how full it is, your coin, and what d would set down. There is nothing to open and nothing to select: you pick things up by walking over them, and you fight with the best of each kind you hold.

   There is sound, synthesised in the page rather than fetched: your move, a hit on you against a hit on something else, a death, a find, a cut. Useful because at eighteen seconds a turn you will look away. A motif plays while you wait for people to answer a call, and a delve ending gets a fanfare, or something rather less pleased. Nothing loops under play. One button turns it all off.

   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.

   --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 it off and it draws in the terminal.

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: Europe, North America, 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.

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 are	Use
   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

   The one thing that can actually fail, so do it first. 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

   Signal strength and packet loss every few seconds. Across a room, about −40 dBm and nothing lost. Between houses, better than −110 is comfortable. 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. They earn nothing from it, because being reachable is not being somewhere. loraline's page covers giving them an address to reach.

When something does not work

The tests fail before any hardware is involved

Almost always loraline not being where catacomms expects. The two folders must sit next to each other, and PYTHONPATH=../loraline points at the outer one, holding README.md.

No port appears

Try a different cable, then a different socket; some carry power only. On older Windows machines the module may need its CH340 or CP210x driver.

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.

Nothing happens for ages after somebody starts cutting

A cut covers sixty ticks on one frame, and if nobody else wants to act the world jumps to the end of it. Move or strike instead of waiting.

The board stays empty however much you delve

You cannot witness your own loot. It needs somebody else present, and both of you heard on the radio rather than over the internet.

It works on the desk but not between houses

Obstruction rather than distance. Antenna higher and nearer a window at both ends, then --sf 12 on every module for range at the cost of speed.