Setting it up

You will type some commands into a black window. That is the only unusual part, and every command you need is written out below to copy. If a step goes wrong there is a list at the bottom of what each failure means.

Two people can do this. Three or four is better. Everyone needs their own module.

1. Buy the radios

   You want the Waveshare USB-TO-LoRa-HF. One per person. They are small, cost around the price of a takeaway each, and plug into a normal USB port.

   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 an LF module cannot talk to an HF one. Everybody in your group needs the same variant.

   The listing may offer a TCXO version for slightly more. Worth it. It keeps the radio on frequency accurately enough to use the long-range settings, which the cheaper crystal version struggles with.

   An antenna is included. Do not buy a better one yet: where you put it matters far more than what it costs, and you will find that out in step 6.

2. Install Python

   Python is the language loraline is written in. You probably already have it. Open a terminal and type python3 --version.

   Windows

   Press Start, type cmd, open Command Prompt. Use python --version instead. If nothing happens, install from python.org and tick Add Python to PATH during setup.

   macOS

   Press Cmd+Space, type Terminal, press Enter. If Python is missing, macOS will offer to install the developer tools. Accept.

   Linux

   You already have it.

   Anything numbered 3.10 or higher is fine.

3. Download loraline

   Go to the repository, click the green Code button, then Download ZIP. Unzip it somewhere you can find again, such as your Desktop.

   Now point your terminal at that folder. Type cd with a space after it, then drag the unzipped folder onto the terminal window and press Enter. That saves you typing the path.

   Check you are in the right place by typing ls on macOS or Linux, or dir on Windows. You should see README.md in the list.

4. Install the two extra pieces

   pip3 install pyserial pynacl

   pyserial lets loraline talk to the USB module. pynacl is the encryption. On Windows use pip rather than pip3, and run one extra command, because Windows does not ship the terminal interface Python needs:

   pip install windows-curses

   Now check the whole thing works, without any radio attached:

   python3 tests.py

   You should see a list of lines beginning ok, ending in ALL PASS. If you get that, the software is fine and anything that goes wrong later is hardware or configuration.

5. Plug in a module and find it

   Plug the first module into a USB port. The computer gives it a name, and you need to know that name.

   Windows

   Open Device Manager, expand Ports (COM & LPT). Yours will be something like COM3.

   macOS

   Run ls /dev/cu.*. Look for something like /dev/cu.usbserial-0001.

   Linux

   Run ls /dev/ttyUSB* /dev/ttyACM*. Usually /dev/ttyUSB0.

   Unplugging it and running the command again is the reliable way to tell which entry is yours: the one that disappears.

   Linux only. If a later step says permission denied, run sudo usermod -aG dialout $USER, then log out of your computer completely and back in. A new terminal window is not enough.

6. Tell both modules which frequency to use

   They arrive tuned to 868 MHz, the European band. Elsewhere that is somebody else's licensed spectrum, so set this before transmitting anything.

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

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

   Replace /dev/ttyUSB0 with your own port name from step 5, and the band with your own. You should see a list of commands each followed by a reply. Then unplug that module, plug in the next one, and run exactly the same command again. Every module in the group must get identical settings.

   These presets cover the common cases. Power limits and duty cycles vary by country, and you are responsible for what your radio transmits.

7. Prove it works, on one computer

   This is the step worth not skipping. Plug both modules into the same computer and have them talk to each other across the desk. If that works, everything except distance is already solved.

   Open two terminal windows, both pointed at the loraline folder. In the first:

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

   In the second, using the other module's port:

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

   You should see replies arriving every few seconds with a signal strength of around −30 to −50 dBm and no loss. That is two radios finding each other.

   Now stop both with Ctrl+C and try the actual client. Pick a passphrase everyone in your group will share:

   export LORALINE_KEY="something you all agree on"
   
   python3 -m loraline chat --port /dev/ttyUSB0 --band eu868 --nick yourname
   
   python3 -m loraline chat --port /dev/ttyUSB1 --band eu868 --nick testing \
       --identity ~/.loraline/second

   On Windows, use set LORALINE_KEY=something you all agree on instead of export.

   Each window fills with a contact list on the left and a conversation on the right. Within a few seconds each should see the other appear. Type in one and it lands in the other, with a double tick when it is confirmed.

   The --identity part matters. Each loraline install has its own key, and two clients on one computer would otherwise share it, decide they were the same person, and ignore each other.

8. Give a module to a friend

   They repeat steps 2 to 4 on their own computer, then run one command. Same band as you, and the same passphrase, which you should tell them in person or by some means other than this radio.

   export LORALINE_KEY="something you all agree on"
   python3 -m loraline chat --port /dev/ttyUSB0 --band eu868 --nick theirname

   Before that, run the link test from step 7 between your two houses. It tells you in seconds whether the path works and how much margin you have, which is far easier to interpret than a chat window that stays quiet.

   Stand the antennas upright. A window sill or an upstairs room beats a desk, by more than any setting in the configuration. If the signal is weak, move the antenna before changing anything else.

Joining from far away, over the internet

Radio only reaches a few kilometres. Someone in another country can still join the same conversation: they connect over the internet to a person who does have a radio, and that person passes messages between the two sides. Everyone ends up in one room. The people near the radio never touch the internet, and the distant person never touches a radio.

The relaying happens on sealed messages, before anything is decrypted, so the person in the middle passes private messages along without being able to read them.

If you have the radio, you host

Your friend needs an address to connect to, and a home internet connection does not usually have one. The straightforward way is Tailscale, which is free for personal use and takes about five minutes.

1. Put both computers on the same private network

   Install Tailscale on your machine and on your friend's, and invite them to your network from the Tailscale admin page. Each machine gets a permanent address starting 100. that works from anywhere, with no router settings to change and nothing exposed to the open internet.

   Find yours: it is shown in the Tailscale app, and also by running tailscale ip -4.

2. Run your client with a door open

   python3 -m loraline chat --port /dev/ttyUSB0 --band eu868 \
       --nick yourname --tcp-listen 4242

   Everything else works exactly as before. The status bar gains a relayed count so you can watch messages crossing between radio and internet.

If you have no radio, you join

This is the short version. Your friend with the radio does all the configuring; you need Python and one command.

1. Install Python

   Open a terminal and type python3 --version, or python --version on Windows. Anything numbered 3.10 or higher is fine. If nothing happens, install it from python.org, and on Windows tick Add Python to PATH during setup.

2. Download loraline

   From the repository, click the green Code button, then Download ZIP. Unzip it. In the terminal type cd with a space, drag the unzipped folder onto the terminal window, and press Enter.

3. Install the two extra pieces

   pip3 install -r requirements.txt

   On Windows use pip rather than pip3. Then check it works, which needs no hardware at all:

   python3 tests.py

   You want a list of lines beginning ok, ending ALL PASS.

4. Join

   Ask your friend for two things: the address of their machine, and the passphrase the group shares. Then:

   export LORALINE_KEY="the passphrase they gave you"
   
   python3 -m loraline chat --nick yourname --tcp-connect 100.x.y.z:4242

   On Windows, use set LORALINE_KEY=the passphrase they gave you instead of the export line.

   No port, no band, no radio settings: you have no radio, so there is nothing to configure. Within a few seconds the contact list on the left fills with everyone else, wherever they happen to be.

If their computer is asleep or their client is closed, yours will keep retrying quietly and connect when they come back. Anything you type while disconnected waits in the queue rather than being lost.

When something does not work

No port appears in step 5

Try a different USB cable, then a different port. Some cables carry power only. On older Windows machines the module may need the CH340 or CP210x driver, which the manufacturer supplies.

Permission denied opening the port

Linux: the dialout group fix in step 5, followed by a full log out. macOS and Windows do not need this.

Every AT command replies "(no reply)"

Either the port name is wrong, or another program has the module open. Close any serial terminal, Arduino IDE or similar, 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, and confirm you are using two different port names for two physically different modules.

They connect but never see each other in chat

Different passphrases. LORALINE_KEY must match exactly, including capitals. If one side has no key set, its group messages go out unencrypted and the other side cannot read them.

The screen is full of strange symbols

Your terminal is not set to UTF-8. On Windows, use Windows Terminal rather than the old Command Prompt window.

The internet connection never comes up

Check the address and that your friend's client is actually running with --tcp-listen. If you are using Tailscale, run tailscale status on both machines and confirm each can see the other.

Connected over the internet, but nobody appears

Almost always a mismatched LORALINE_KEY. It must match exactly, capitals included.

It works on the desk but not between houses

This is the expected problem, and it is about obstruction rather than distance. Get the antenna higher and nearer a window at both ends, then try --sf 12 on every module for maximum range at the cost of speed. Check the range table for what to expect.

Once it is working

Press Tab to move between the group conversation and private ones. Type /help to see everything. /w followed by someone's name opens a private chat with them that nobody else can read, including anyone relaying it.

Then leave it running. The thing that makes it feel like it used to is seeing somebody appear.