Using Tern

What each part of Tern does, from the first connection on. It assumes a board with Tern on it: if yours has none yet, flash it first.

Connecting an app

The node does the radio; the app is its keyboard and screen. The phone apps and the browser app reach it over Bluetooth, and the browser app over USB too. The node takes one Bluetooth client and one USB client at a time, and both see the same contacts and messages.

Turn the node on, and open the app. It looks for nodes nearby: each shows as Tern.
Choose yours. The node's screen shows a six-digit passkey: type it into the app. The pairing is remembered, so this is once per phone. A passkey can also be fixed in the app's node settings, for a board without a screen.
A node new to the app asks three things: its region, which it must have; whether it is a leaf or a relay; and, if you like, a first contact.

The phone apps keep the link up in the background and notify you of new messages, and you can reply from the notification. The browser app works only while its page is open. The node keeps your recent messages itself, so an app that was away catches up when it connects again.

Region, role and power

Region: The frequency and the rules the node sends by: US915 (the United States and Canada), EU868 (Europe), AU915 (Australia) or NZ915 (New Zealand). It must be the one where the node is used, and nodes only hear others in the same region. In EU868 a node may send for at most 10% of any hour, and counts its time on the air to keep to it.
Role: A leaf sends and receives its own messages only: best for a node you carry. A relay also passes on messages for others, which lets the mesh reach further but uses more battery: best for a node left somewhere high, on power. You can change it at any time.
Transmit power: How loud the node sends. It starts low, enough for a desk; raise it for distance. The node refuses a power that, with the antenna's gain, is more than the region allows. A node with current firmware can also work out and use the most it may send at for its board, antenna and region.

Each is changed from the app's node screen.

Contacts

A node's address is its public key: sixty-four hex digits, which nobody types. People exchange them instead as a link (ternmesh.org/a/…) or its QR code, which the node's Share screen and every app show. To add someone, scan their code, open their link, or paste it into the app's add form, and give them a name. The name is yours: it never goes on the air.

Beside every address is its short code, twelve digits. Compare it with the person, face to face or on a call: if it matches, the address you hold is really theirs. It is a quick check; the full address in the QR code is the strong one.

Your node takes a first message from anyone you have saved as a contact. Someone you have not saved may be turned away once your node has conversations going; the app tells you who asked, so you can add them and try again.

Messages

A message holds up to 128 bytes of text: about 128 letters of English, fewer with accents or emoji. Each one you send shows where it is:

State	What it means
Waiting	Not on the air yet, and the app says why: looking for a route to them, setting up a secure session, the region's transmit limit, or the radio busy. It goes by itself once it can.
Sent	A node on the way was heard passing it on. It has left your node, and not yet arrived.
Delivered	Their node says it has it: the acknowledgement came back all the way.
Not delivered	Your node tried for a while and gave up. It may be out of reach, off, or unable to set up a session: see Troubleshooting.

A message is delivered to their node, which keeps it until their app collects it, so they need not be connected when you write.

Secure sessions, and how many

The first time two nodes write, they set up a secure session: four short frames, two or three seconds, after which only those two nodes can read what passes between them. It happens by itself, and the message waits for it.

A node holds a session with each person it writes to, and has room for a fixed number: 8 on the current release. Once it is full, writing to someone new is not delivered until you end a session you no longer need, from that conversation in the app (End session). Ending one costs nothing but a new handshake the next time you write. The next release raises this to 16 sessions on ESP32-S3 and nRF52840 boards, with 32 contacts and 8 groups.

Groups

A group is a conversation among everyone who holds its secret. Make one in the app and invite contacts to it, over their sessions; or show its join code, a link and a QR code, and let people join from that.

Anyone who sees a join code can read the group, now and later. Show it only to people you mean to let in, and make a new group if it leaks.

In a group, each message carries who wrote it as that node claims, and the app shows a contact's name where it knows the writer. Leaving a group is quiet: the others are not told. Tern has no public channel that everyone is in; to find people nearby, see the next section.

Who is about

A node can send a presence card now and then: its address and a name, so that people near it can find it and add it. The app lists the cards your node has heard, each name shown as its sender's claim beside the address's short code.

Your own card is off until you turn it on. On, it puts your node's address and the name you give it on the air in clear, every couple of hours, for anyone listening. Turn it off again from the same switch.

Sharing your position

You choose who sees where you are, and how exactly: share with a contact or a group, at a precision from a few metres to a whole region, for a time or until you stop. The phone gives the node its location only while the node shares with someone, and the node rounds it to each person's precision before anything goes on the air. Positions shared with you appear on the app's map.

A node with a GPS of its own knows where it is without the phone. The browser app shows that fix on the node's card, with how many satellites it came from, and can turn the GPS off under Settings to save the battery; the node keeps its last fix, and shares it, like any position, only with those you share with.

The map's tiles come from OpenFreeMap on Android and from Apple on iPhone, so those servers see which area the map shows. The privacy page has the rest.

The node's screen and button

The node works on its own too. Its screen has a few pages, and one button: PRG on a Heltec board, and the user button on others:

Press it to show the next page. A press while the screen is dark only wakes it.
Hold it for a second to act on the page shown: the next message, the next nodes, a group's join code.
Hold it for five seconds to turn the node off; the screen counts down from the second, and letting go keeps it on. A press turns it on again.

The browser app can turn the node off too, with Turn off beside Disconnect, once its firmware speaks version 9 of the companion protocol. Nothing reaches a node that is off: it is turned on again only at the node, by its button, its reset or its power.

Home: New messages, how many nodes it hears, the battery and the region.
Messages: One at a time, newest first, with what became of those you sent.
Nearby: The nodes it hears directly, and how well.
Air: How much of the region's limit on the air is used.
Share: Its address as a QR code, and its short code: what someone scans to add you.
This node: Its short code and address, role, region, power and firmware version.
Groups: The groups it holds; hold PRG to show one's join code.
Phones: The phones paired with it; hold PRG twice to forget them all.
Reset: Erases the node for a new owner: hold PRG, then hold it again within ten seconds. It starts again with a new address, and everything it held is gone.

The LED blinks for every frame sent or heard, and briefly every four seconds while a message is unread. At 10% battery Home says Low, and below 3.3 V the node turns itself off rather than run the cell flat. Boards without a screen or a button, listed on Hardware, are used from an app alone.

Updating the firmware

When a newer release is out, the apps offer it on the node screen and send it over Bluetooth: a few minutes, with the node working as usual meanwhile. If the link drops, it goes on from where it stopped. The node keeps its address, contacts, sessions, groups, messages and settings, and goes back to the old firmware by itself if the new one will not start.

Updating over Bluetooth works on ESP32 boards that were flashed with release 0.2.0 or later. An older one is updated once from the flash page, choosing Update, which keeps its address; nRF52840 boards are updated by copying the release's .uf2 file onto them, as when they were first flashed.

The serial console

For the curious: a node plugged in over USB has a text console at 115200 baud, where status, routes, peers and a dozen more commands show and do what the apps do, and some they do not. The list is in the firmware's README.