loraline

── everyone ─────────────────────────
hank                    │╱╱╲  loraline. Signed in as hank (dd764c).
Online                  │* 868 MHz (ch 18)  SF7  BW125  8 dBm
listening to something  │* Listening on 868 MHz. Everyone must match.
dd764c                  │* Idle costs 10s of radio time an hour, of 36.
                        │* dave has just signed in.
▸ everyone              │21:04 dave: antenna is in the attic now
    2 online            │21:04 hank: that's the whole difference ✓✓ 2/2
  ● dave (1)            │21:06 mira: still nothing from the cellar
    Online              │21:07 hank: try a window. height beats power,
    brb dinner          │             every single time ✓· 1/2
  ● mira                │
    Online              │
                        │
signal ||||  -88 dBm    │
▁▃▅▇▆▄▂▄▅▇█▆            │
last heard 12s ago      │mira is writing a message...
                        │[everyone] ▌
868 MHz   22s of radio time left this hour   1 waiting   encrypted for the group

Three people, one radio channel, no infrastructure between them.

What it is

Two or more people plug a LoRa module into a USB port and talk to each other. No server, no account, no phone app, no internet. The radio in your house reaches the radio in theirs, and there is nothing else involved.

It borrows its shape from MSN Messenger: a contact list, presence, a personal message, private windows alongside the group. Those existed because the medium was thin, and this medium is thin again. When the heartbeats stop, your friend has gone. No server is guessing on their behalf.

Range is a few kilometres in a town, more with a window and some height. It is for people who are already near each other.

What you need

• Two or more Waveshare USB-TO-LoRa-HF modules, or the near-identical EBYTE equivalents. They appear as a serial port and need no firmware flashing.
• An antenna each. This matters more than any setting you can change.
• Nothing, for the app: Python is inside it. For the command line version, Python 3.9 or newer.

The only dependencies are pyserial, and pynacl if you want encryption.

Getting started

Download it, open it, and answer three questions: what people should call you, the passphrase your group agreed, and where in the world you are. It finds the module itself and sets the frequency itself. The second time it asks nothing.

There is nothing to install and no terminal involved. The command line is still there for anybody who prefers it.

Radio and internet, together

A node can hold more than one bearer at a time, and one holding both becomes a bridge. That lets somebody far away join over the internet while the people near you stay entirely on radio.

# you: radio to the neighbours, socket to everyone else
python -m loraline chat --port /dev/ttyUSB0 --band eu868 \
    --nick hank --tcp-listen 4242

# next door: radio only, no internet at all
python -m loraline chat --port /dev/ttyUSB0 --band eu868 --nick dave

# far away: no radio at all, so no band to set either
python -m loraline chat --nick will \
    --tcp-connect your-host.example.com:4242

Relaying happens on sealed envelopes, before anything is decrypted, so the bridge passes a private message between two of its peers along without being able to read it. Whoever joins this way needs no radio and nothing configured. There are instructions for both sides.

This is how networks worked before there was one big one. FidoNet was thousands of machines that each called a neighbour nightly, and mail crossed continents by hopping between local links. Nobody had a global connection. They had a link to someone who had a link.

Who can read what

Every module on the channel receives every packet, so a private chat cannot rely on clients politely ignoring what isn't theirs. Anyone with a modified client, or a serial terminal, would read it.

Each install generates a keypair in ~/.loraline/identity, and your address is the hash of its public halves. Addresses are exchanged the first time two people hear each other.

Group messages

Encrypted with a passphrase you all share. Everyone who has it can read them; nobody else can.

Private messages

Encrypted between exactly two identities. The third person in the group cannot read them, even though their radio received every byte.

Nothing about routing travels in the open, so a listener nearby cannot tell who a packet is addressed to. /whois dave shows a fingerprint to compare out loud: key exchange over the air is safe from a listener but not from an active impersonator.

What it can't do

Range is decided by obstruction, not distance

Modern low-emissivity window coatings are metal oxide and cost you 15 to 25 decibels on their own. Getting the antenna two metres higher will do more than any parameter in the config.

Airtime limits the group, not the code

Everyone announces themselves periodically, and if two transmit at once both packets are lost. Five or six people works where there is no duty cycle cap. Under the European 1% limit, three is comfortable and four is optimistic.

Presence is the only thing that transmits when nobody is talking, so it sets the floor on what an idle client costs. The client works that out at startup and tells you. If a heartbeat a minute would not fit, it slows presence down and says by how much.

It is slow, and always will be

A forty-character message spends about 120 milliseconds on the air at spreading factor 7, or roughly 740 at spreading factor 10, and about double either figure once encrypted. The client shows the budget you have left in the hour and holds messages back rather than pretending they were sent.

The European preset uses the faster, shorter-range setting by default. Under a 1% cap a high spreading factor spends the whole hourly allowance on saying hello.

Who you are

A nick, a colour, a line about what you are up to, and a face. All of it is set once and kept beside your keypair, and all of it is identity rather than anything to do with a particular application: you look the same in the chat, in the dungeon and on the shore.

The picture is thirty-two pixels and eight colours, and it can be a photograph. Everybody has one derived from their address before they set one, so nobody is ever a blank square.

Your address is sixteen hex characters, derived from both your keys. It is what every signature here is checked against, so it has to be long enough that nobody can sit at a laptop making keypairs until one comes out with your address on it. Sixty-four bits is millions of years of that.

A picture is too big to travel the way a nick does, so it does not. Your heartbeat carries six characters saying which picture you have; anybody who does not have that one asks for it, once, and then never again.

It stays running

A radio is a thing other people talk to, so closing the window does not quit. Messages arrive when you are not looking, and if somebody is reaching the group through you, your window being shut is them being cut off.

Starting with the computer is offered once and is one click to undo. Nothing installs itself.

What rides on it

A serial port can only be opened once, so two programs cannot share a radio. loraline owns it, and anything else that wants the air rides along in the same window: one setup, one airtime budget, one conversation underneath, and a switcher across the top.

Whatever is installed appears; whatever is not, does not.

Source

Around two thousand lines of Python, in five parts: the wire protocol, the session state, the transports, a driver, and a terminal interface. The session logic is pure, taking frames and clock ticks in and giving events out, so the test suite runs three conversations over a simulated lossy radio and a real socket pair without any hardware attached.

git clone https://github.com/intervalplace/loraline
cd loraline
python tests.py          # three sessions, simulated radio
python tests_bridge.py   # radio and internet bridged