Playing it

Two minutes to a line in the water, with nothing but a laptop. The radios come later, when you want company.

On your own

  1. Check you have Python

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

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

  2. Download the two folders

    longshore 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 longshore repository and the loraline one, click the green Code button on each, then Download ZIP. Unzip both next to each other.

    Point the terminal at the game folder: type cd with a space, drag the unzipped longshore folder onto the window, press Enter.

  3. Install the two pieces

    pip3 install pyserial pynacl

    On Windows use pip. Then check it works, with no hardware:

    PYTHONPATH=../loraline python3 tests.py

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

    You want lines beginning ok, ending ALL PASS.

  4. Go to the coast

    PYTHONPATH=../loraline python3 -m longshore --nick yourname --coast ourbay

    Open localhost:8080. Tap the water to fish it, the land to walk, and tap again when the float goes red.

    Arrow keys walk, space casts and strikes. What anybody says appears over their head. There is sound, synthesised in the page; the one that matters is the knock when something takes your float, because you will be looking somewhere else.

    The page is served on every interface, so the radio can stay plugged into a laptop while you play from a phone on the same network: open http://that-machine:8080. Tapping is the whole interface anyway.

    --coast is which coastline. Any word will do, but everybody in your group must type the same one, or you will each be on your own coast, alone.

With other people

  1. Buy the radios

    One Waveshare USB-TO-LoRa-HF per person. Small, about the price of a takeaway each, plugs into a normal USB port.

    Watch the last two letters. HF covers 868 and 915 MHz: Europe, North America, Australia. LF is a different band and cannot talk to an HF unit. The TCXO version costs slightly more and is worth it.

  2. Set the frequency, before transmitting anything

    They arrive tuned to 868 MHz. 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 with ls /dev/cu.* on macOS, ls /dev/ttyUSB* on Linux, or Device Manager under Ports on Windows. On macOS use cu. and never tty., which will hang.

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

    Every module gets the same command.

    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 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, the same with --role ping. Across a room, about −40 dBm and nothing lost. Between houses, better than −110 is comfortable. Stand the antennas upright and near a window.

  4. Go together

    Agree a passphrase in person, and the same coast. Then everybody runs:

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

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

    Within a few seconds the others appear on the shore. Anything you type in the box is said out loud to everybody.

  5. Somebody far away

    A person with no radio can join by reaching somebody who has one. Whoever holds a radio adds --tcp-listen 4242; the distant one runs no radio:

    PYTHONPATH=../loraline python3 -m longshore --nick theirname \
    --coast ourbay --tcp-connect your-address:4242

    The people near you never touch the internet, the distant one never touches a radio, and everyone is on the same shore. 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 longshore expects. The two folders must sit next to each other, and PYTHONPATH=../loraline points at the outer one, holding README.md.
Everyone is on a different coast
Different --coast words. It has to match exactly.
Nothing bites for ages
A bite takes up to twenty-four seconds. If it has been longer than that, you are probably not casting: check the line is out and the float is on the water.
You cannot cast at all
You are not beside water. Tap the sea rather than the sand and you will walk to somewhere you can fish from.
Tapping some water does nothing
There is no way to walk to it. A coast has islands, and you cannot swim.
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.
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 --identity ~/.loraline/second.
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.