v0.3.0-alpha.1

The first alpha of 0.3. A board shares its position with the contacts and groups its user
chooses, a group message recorded off the air is no longer read a second time, and there are
images for two more boards, neither of which has run on one yet.

It is an alpha. The protocol is a draft and will change, and a later build may not talk to this
one or keep its sessions. Nobody outside the project has reviewed the cryptography. Do not rely
on it for anything that matters.

Group messages do not pass between this release and any before it. Update every board in a
group together: see Updating.

What changed

• Positions. A client gives the board where it is, and the board shares it with the contacts
  and groups the user chooses, as a cell of a grid as coarse as the user chooses, for as long as
  they choose. To a contact it goes sealed and acknowledged as a message does, and only over a
  session the two already have; to a group it goes as a group message does, and only when that
  leaves room for words. The board has no receiver of its own: it shares nothing until a client
  has given it a position. Sharing is not kept through a restart, and a client is told it is
  off.
• A group message is read once. Each group message carries a count from its writer, sealed
  with the words, and a board that has read it does not read it again, after a restart either.
  Before this, anyone who had recorded a group message could send it again with no key, and a
  board would in time show it as new. A board keeps the counts of sixteen writers a group. A
  group message is four bytes longer.
• A frame for every node is known by all of its bytes. The first byte was left out, so a
  node could change it, send the copy on ahead, and have relays take the real frame for one
  they had already passed on.
• The companion protocol is at version 5: a client's position, sharing with a contact or a
  group, and the positions the board hears. A client that speaks an earlier version works as
  before, and is told nothing of positions.
• Heltec WiFi LoRa 32 V4: tern-heltec-v4-… images. Built from Heltec's schematics and the
  amplifier's datasheet. Nobody has run it on a V4.
• Heltec Mesh Node T114 V2, the first nRF52840 board: tern-heltec-t114-….uf2 images, on
  Zephyr, with the same commands, screen pages, companion link and Bluetooth service. It cannot
  be given firmware over the link. Nobody has run it on a T114.
• One node for every board. What a board does is now the same code on each, with the chip's
  own parts behind it. On a Heltec V3 the only differences are that a storage fault and a
  console that does not start are shown, where the board used to restart.

First contact, sessions, messages to one board and routes are the same on the air as in
0.2.0-alpha.1.

What was tested, and what was not

On two Heltec V3 boards, over USB, with a build of the commit this release is made from:

• A board running 0.2.0-alpha.1 was updated over the link with -app.bin, and restarted into
  the new firmware with its address, contact, session, group and saved messages. It had been put
  back on 0.2.0-alpha.1 for this, so its group had been saved by the newer firmware: a group
  made on 0.2.0-alpha.1 was carried over once, on an earlier build, and not again for this
  release.
• A board on 0.2.0-alpha.1 and one on this exchanged messages both ways, over the session they
  had.
• Messages both ways, each acknowledged, and still there after a restart.
• Group messages both ways, before and after a restart of both boards.

Not tested on a board as part of this release: positions, to a contact or to a group; a recorded
group message sent again, which rests on tests on a computer; Bluetooth; and more than two boards,
so no frame was passed on along a route. The V4 and T114 images have been built and nothing
more: if you have either board, what it does when it starts is the report we most want, and
the checklist is in docs/boards.md. Measure a V4's power before trusting it:
the amplifier's gain is taken from a datasheet, and the board could send more than it is asked
to.

Updating

A Heltec V3 on 0.2.0-alpha.1 takes this release over the link, and keeps its address, sessions,
contacts, groups, messages, settings and paired phones:

tools/companion.py --port <port> update tern-heltec-v3-<region>-0.3.0-alpha.1-app.bin

A board that has had this release does not read the group messages of one that has not, and the
other way round. Neither shows anything. Update every board in a group, and the group is as it
was: nobody has to be invited again.

A board on a release before 0.2.0 is moved over USB, once, with two images:

tern-heltec-v3-<region>-0.3.0-alpha.1-boot.bin	at 0x0
tern-heltec-v3-<region>-0.3.0-alpha.1-update.bin	at 0xF000

Do not write -app.bin at 0x10000, as the first releases said to.

For a new node, or to start a board afresh with a new address:

tern-<board>-us915-0.3.0-alpha.1.bin	United States, Canada: 921.25 MHz
tern-<board>-eu868-0.3.0-alpha.1.bin	Europe: 869.475 MHz, at most 10% of any hour

<board> is heltec-v3 or heltec-v4. The full images are written at 0x0 and replace
whatever is on the board. A T114 takes tern-heltec-t114-<region>-0.3.0-alpha.1.uf2: press RST
twice, and copy the file onto the drive HT-n5262 that appears
(ports/nrf52). Never power a board with nothing on the
antenna connector. SHA256SUMS has the SHA-256 of each image.

What to know

• An update is not signed. Anyone who has paired with a board can give it firmware, as they
  can change its region.
• Saved messages and keys are not encrypted, a group's secret among them. Anyone holding
  the board can read them.
• A member of a group can write as any other member, and a group's messages have no
  forward secrecy: whoever learns the group's secret reads what was recorded before.
• A position is as private as what carries it. To a contact, that is a session; to a
  group, everyone who holds the group's secret.

What is still not in it

• No message to everyone. A group is those who were invited; there is no public channel.
• Boards start at 2 dBm, a bench setting that reaches across a building, not a town, until
  you raise it. A V4 starts at 4 dBm.
• No presence cards, though the specification has a draft of them.

v0.2.0-alpha.1

The first alpha of 0.2, for Heltec WiFi LoRa 32 V3 boards. A board can now be given new firmware
over its companion link, without a cable once it runs this release, and it keeps its messages
through a restart.

It is an alpha. The protocol is a draft and will change, and a later build may not talk to this
one or keep its sessions. Nobody outside the project has reviewed the cryptography. Do not rely
on it for anything that matters.

Moving a board to this release is different from every release before it. Read
Updating first: the image that used to go at 0x10000 no longer goes there.

What changed

• Updates over the link. A client gives the board new firmware over USB or Bluetooth:
  tools/companion.py --port <port> update <image> from a computer, and the phone apps the
  same way. The image is the release's -app.bin, about 700 KB. The board stays on the air
  while it arrives, and a link that drops goes on from where it stopped. Everything the board
  saves stays: its address, sessions, contacts, groups, messages, settings and paired phones.
• A board goes back if the new firmware does not start. The flash now holds two copies of
  the firmware. An update is written to the one not running, and kept only once it is on the
  air; if it halts or restarts before then, the board runs the one it had.
• Messages are saved to flash. The last messages sent and received come back after a
  restart or a flat battery, with what became of each. About 16 to 26 fit, by their length; when
  there is no room the oldest give way and the newest are kept. A message that was waiting to go
  when the board restarted is shown as not delivered if the board had already begun to send it,
  and goes otherwise.
• A busy board passes fewer group messages on. Once its radio has spent more than a fifth
  of the last half minute to minute sending or receiving, a relay drops some of the group
  frames it would pass on, more of them the busier it is, and its own never. In the simulator
  this gives messages to one board back what group messages were taking where the channel is
  full, and changes nothing where it has room.
• The companion protocol is at version 4. Version 3 tells a client how much news the board
  has for it; version 4 is updates, and names the board and its release. A client that speaks an
  earlier version works as before.
• The screen. A boot screen, and why a board did not start if it did not. Holding PRG turns
  the board off. The battery says when it is low, charging or empty. Home shows when a phone is
  connected, group messages are shown by group and writer, there is a page of the boards
  nearby, and the LED blinks while a message is unread. Paired phones can be forgotten, and the
  board erased, from the screen.

No frame on the air has changed since 0.1.0-alpha.4.

What was tested, and what was not

On two boards, over USB:

• A board on the old layout moved to this one with the two images below. It kept its address,
  its sessions and its saved messages, and exchanged messages with a board still on the old
  layout, and then with one on the new.
• An update over the link from a computer: 715 KB in just under four minutes. The board
  restarted into the new firmware, kept everything, and stayed on it through a reset.
• Two images made to fail, one that halts as it starts and one that restarts before it is on
  the air. Each time the board went back to the firmware it had, with everything kept.

Not tested as part of this release: an update over Bluetooth, from a phone or otherwise; an
update whose link drops part-way; whether a paired phone is still paired after the move to the
new layout; and the screen's new pages. A busy board dropping group frames has run in tests on a
computer and in the simulator, and never comes into play between two boards. If you see any of
these misbehave, those are the reports we most want.

Updating

Do not write -app.bin at 0x10000. Every release before this one said to. There is no
firmware at that address any more, and -app.bin is now only what a client sends over the link.

To move a board that runs an earlier release and keep its address, sessions, contacts and
paired phones, write two images over USB, once:

tern-heltec-v3-<region>-0.2.0-alpha.1-boot.bin	at 0x0
tern-heltec-v3-<region>-0.2.0-alpha.1-update.bin	at 0xF000

https://ternmesh.org/flash does this when you say the board runs Tern already, once the
page offers this release. From then on the board can be updated over the link.

For a new node, or to start a board afresh with a new address:

tern-heltec-v3-us915-0.2.0-alpha.1.bin	United States, Canada: 921.25 MHz
tern-heltec-v3-eu868-0.2.0-alpha.1.bin	Europe: 869.475 MHz, at most 10% of any hour

The full images are written at 0x0 and replace whatever is on the board. Never power a board
with nothing on the antenna connector. SHA256SUMS has the SHA-256 of each image.

This build and 0.1.0-alpha.4 work together on the air: first contact, sessions they already
have, messages and groups.

What to know

• An update is not signed. Anyone who has paired with a board can give it firmware, as they
  can change its region. The digest a client sends says the image arrived whole, not who made
  it.
• Saved messages are not encrypted, like the keys beside them. Anyone holding the board can
  read them.
• A message sent twice. A client that asks again for a message to be sent, after a restart
  of the board, has it sent again: the board does not remember across a restart that it was
  asked.
• An old group message can be sent again by anyone who recorded it, and is read as new, as
  in 0.1.0-alpha.4.

What is still not in it

• No message to everyone. A group is those who were invited; there is no public channel.
• Boards start at 2 dBm, a bench setting that reaches across a building, not a town, until
  you raise it.
• Keys sit in flash unencrypted, a group's secret among them.
• One board only. An nRF52 port is next.

v0.1.0-alpha.4

The fourth alpha, for Heltec WiFi LoRa 32 V3 boards. It adds groups: a conversation among several
boards, where every message so far was to one. The board's screen is also now one for the person
carrying it, and shows its address as a code a phone can scan.

It is an alpha. The protocol is a draft and will change, and a later build may not talk to this
one or keep its sessions. Nobody outside the project has reviewed the cryptography. Do not rely
on it for anything that matters.

What changed

• Groups. A group is the boards that hold one secret. A message to it is one frame that
  every relay in reach passes on once, unless it hears another do so first, and every board that
  holds the secret reads. A board holds up to four. From the console: group new <name>,
  group invite <number>, group join <id>, group send <number> <text>, group leave <number>, and groups to list them. The app at https://ternmesh.org/app does the same.
• Invites. A board is handed a group by one that has it, over the session the two share. It
  is shown the invite, and holds the group only once someone joins.
• The companion protocol is at version 2, which is how a client reaches groups. A client that
  speaks version 1 works as before, and is told nothing of them.
• A screen for the person carrying the board. Pressing PRG moves through Home, Messages, Air,
  Share and This node. A message that arrives turns the screen on and shows it. The pages of
  routing ids and frame counts are still there for a bench: screen bench on.
• An address a phone can scan. The Share page shows the board's address as a QR code, which
  opens a page on ternmesh.org that shows the address and a twelve-digit short code to check it
  by. contact on the console takes that link as well as the sixty-four digits.
• The battery is read, and Home and the app show the charge, where they showed nothing.

What to know about groups

• Any member can write as any other. Everyone in a group holds the same key. A message says
  who wrote it, and any member could have said so.
• Whoever gets the secret reads everything, frames they recorded before included, and nobody
  can be put out of a group. The others start a new one.
• Nothing says a message arrived. A group message is waiting, then sent once it has gone on
  the air. No board answers it.
• A board writes only so much. Its own group messages take at most 0.5% of its time: about
  two dozen short ones at once and one every 25 seconds after. It spends up to 3% of its time
  passing on other boards'. Neither number has been measured against anything.
• An old message can be sent again by anyone who recorded it, and is read as new. A board
  knows a group frame it has had only by the last 64 it read in that group, and forgets those
  when it restarts. A frame older than that, recorded off the air and sent again, shows as a new
  message with its old words. Nobody need hold the group's secret to do it.
• An invite not joined before a restart is gone.

Groups were run between two boards in range of each other, from the console and from the app's
own code over USB: a group made, an invite sent and joined, messages each way. A group message
has not been further than one hop on real radios, and relays staying silent on hearing another
pass a frame on has only run in tests on a computer. The app's pages for groups, the new screen,
the QR code and the battery reading were not checked on a board as part of this release's own
testing. If you have three boards, or see any of these misbehave, those are the reports we most
want.

Updating

Update every board that should carry a group's messages. A board on 0.1.0-alpha.3 does not
pass group messages on and cannot take an invite. Everything else works between this build and
that one: first contact, sessions they already have, and messages.

A board running an earlier alpha keeps its address, sessions and contacts if you write the
-app.bin image at 0x10000; https://ternmesh.org/flash does that when you say the board runs
Tern already.

tern-heltec-v3-us915-0.1.0-alpha.4.bin	United States, Canada: 921.25 MHz
tern-heltec-v3-eu868-0.1.0-alpha.4.bin	Europe: 869.475 MHz, at most 10% of any hour

The full images are written at 0x0, replace whatever is on the board, and give it a new
address. Never power a board with nothing on the antenna connector. SHA256SUMS has the
SHA-256 of each image.

What is still not in it

• No message to everyone. A group is those who were invited; there is no public channel.
• Messages are kept only in memory on the board. The web client keeps what it has seen in
  the browser; a message that arrives while no client is connected is lost if the board restarts
  before one connects.
• No phone app. The web client reaches a board over Bluetooth from Chrome on Android, and
  not from an iPhone.
• Boards start at 2 dBm, a bench setting that reaches across a building, not a town, until
  you raise it.
• Keys sit in flash unencrypted, a group's secret among them. Anyone holding the board can
  read them.
• One board only. An nRF52 port is next.

v0.1.0-alpha.3

The third alpha, for Heltec WiFi LoRa 32 V3 boards. Two boards no longer have to hear each other
to meet: first contact goes through relays, as messages already did.

It is an alpha. The protocol is a draft and will change, and a later build may not talk to this
one or keep its sessions. Nobody outside the project has reviewed the cryptography. Do not rely
on it for anything that matters.

What changed

• First contact follows routes. The four frames of the handshake are passed on by relays, hop
  by hop, so a board can make a session with any board it has a route to. Until now the two had
  to be in range of each other to meet, and only then could their messages go through a mesh.
• A lost handshake frame is sent again as a lost message is. The board that began waits five
  seconds and a little for each answer, tries up to four times, and then says it gave up. The
  other board answers again when asked and never sends unasked.
• A board that starts a handshake again is answered at once. It used to wait out the one it
  had left.
• A handshake's frames now name both boards' routing ids, as a message and its acknowledgement
  do between them. Neither address is on the air.

This was run on two boards in range of each other, and through a relay only in tests on a
computer: the project has two boards. If you have three and can put the middle one between two
that do not hear each other, that is the report we most want.

Updating

Update every board together. The handshake's frames changed, so a board on this build and
one on 0.1.0-alpha.2 cannot make first contact with each other. Sessions they already have keep
working, and messages still pass between them.

A board running an earlier alpha keeps its address, sessions and contacts if you write the
-app.bin image at 0x10000; https://ternmesh.org/flash does that when you say the board runs
Tern already.

tern-heltec-v3-us915-0.1.0-alpha.3.bin	United States, Canada: 921.25 MHz
tern-heltec-v3-eu868-0.1.0-alpha.3.bin	Europe: 869.475 MHz, at most 10% of any hour

The full images are written at 0x0, replace whatever is on the board, and give it a new
address. Never power a board with nothing on the antenna connector. SHA256SUMS has the
SHA-256 of each image.

What is still not in it

• No group or broadcast messages. Every message is to one address.
• Messages are kept only in memory on the board. The web client keeps what it has seen in
  the browser; a message that arrives while no client is connected is lost if the board restarts
  before one connects.
• The web client does not use Bluetooth yet, so there is no phone client.
• Boards start at 2 dBm, a bench setting that reaches across a building, not a town, until
  you raise it.
• Keys sit in flash unencrypted. Anyone holding the board can read them.
• One board only. An nRF52 port is next.

v0.1.0-alpha.2

The second alpha, for the same two Heltec WiFi LoRa 32 V3 boards and as many more as you have. It
is what the first one lacked to get past two boards on a desk without a serial terminal.

It is an alpha. The protocol is a draft and will change, and a later build may not talk to this
one or keep its sessions. Nobody outside the project has reviewed the cryptography. Do not rely
on it for anything that matters.

What changed

• A new board is let in from the web client. A board accepts first contact from any address
  saved as a contact. When it refuses one for not being a contact, the client says who asked and
  offers to save it; that board is taken the next time it tries. A board that already holds
  eight sessions refuses for want of room instead, and the client says so: end a session first.
  accept on the console still works.
• A session can be ended from the web client. The board forgets its keys for that node and
  gives up the messages still waiting for it. The other board is not told: its messages go
  unanswered until the board that ended it sends a message, or the other ends its session too.
• The web client sets power, region and role. The board restarts to apply one, and the page
  connects again.
• The companion protocol is version 1: END_SESSION and ASKED are new. A client of version 0
  works as before.

Updating

A board running 0.1.0-alpha.1 keeps its address, sessions and contacts if you write the
-app.bin image at 0x10000; https://ternmesh.org/flash does that when you say the board runs
Tern already.
This build talks to 0.1.0-alpha.1 on the air.

tern-heltec-v3-us915-0.1.0-alpha.2.bin	United States, Canada: 921.25 MHz
tern-heltec-v3-eu868-0.1.0-alpha.2.bin	Europe: 869.475 MHz, at most 10% of any hour

The full images are written at 0x0, replace whatever is on the board, and give it a new
address. Never power a board with nothing on the antenna connector. SHA256SUMS has the
SHA-256 of each image.

What is still not in it

• First contact does not follow routes. Two boards must hear each other directly to meet.
  Once they have, messages between them may go through relays.
• No group or broadcast messages. Every message is to one address.
• Messages are kept only in memory on the board. The web client keeps what it has seen in
  the browser; a message that arrives while no client is connected is lost if the board restarts
  before one connects.
• The web client does not use Bluetooth yet, so there is no phone client.
• Boards start at 2 dBm, a bench setting that reaches across a building, not a town, until
  you raise it.
• Keys sit in flash unencrypted. Anyone holding the board can read them.
• One board only. An nRF52 port is next.

v0.1.0-alpha.1

The first build meant for someone other than its authors: two Heltec WiFi LoRa 32 V3 boards that
find each other, set up a session and send each other encrypted messages, driven from a web page.

It is an alpha. The protocol is a draft and will change, and a later build may not talk to this
one or keep its sessions. Nobody outside the project has reviewed the cryptography. Do not rely
on it for anything that matters.

What you need

• Two Heltec WiFi LoRa 32 V3 boards (ESP32-S3 and SX1262, the 863-928 MHz kind), each with its
  antenna fitted. Never power a board with nothing on the antenna connector.
• Chrome or Edge on a computer, and a USB cable that carries data.

Flashing

Take the image for where you are. A board sends on its region's frequency as soon as it starts,
so the wrong image breaks the rules of the place you are in.

tern-heltec-v3-us915-0.1.0-alpha.1.bin	United States, Canada: 921.25 MHz
tern-heltec-v3-eu868-0.1.0-alpha.1.bin	Europe: 869.475 MHz, at most 10% of any hour

Write it at address 0x0, with esptool-js in the
browser or esptool.py write_flash 0x0 <image>. This replaces whatever is on the board,
Meshtastic or MeshCore included, and the board starts with a new address. The
port's README
has the steps.

The -app.bin images are the application alone, for a board that already runs Tern: written at
0x10000, they leave its address, sessions and contacts as they are.

SHA256SUMS has the SHA-256 of each image.

Using it

Open https://ternmesh.org/app and press Connect over USB. Add the other board as a
contact by its address, which its own page shows, and send it a message. The first message
makes first contact, which takes a few seconds; after that a message is delivered when the other
board's acknowledgement comes back.

A board with no session accepts whoever makes contact with it. One that already has a session
refuses a board it does not know until accept is typed on its serial console, which lets one
in for two minutes. So a third board needs a terminal for now.

The serial console (115200 baud) does all of this from a terminal as well: the
port's README
lists the commands.

What is in it

• First contact and encrypted, acknowledged messages between boards, with a session with each of
  up to eight others.
• Routes: boards announce themselves, a message follows the route to its destination, and a
  board built as a relay passes others' frames on.
• Listening first: a board sends nothing while its radio is receiving a frame.
• The companion link over USB and Bluetooth LE, and the web client over USB.

What is not

• First contact does not follow routes. Two boards must hear each other directly to meet.
  Once they have, messages between them may go through relays.
• No group or broadcast messages. Every message is to one address.
• Messages are kept only in memory on the board. The web client keeps what it has seen in
  the browser; a message that arrives while no client is connected is lost if the board restarts
  before one connects.
• A session cannot be ended from the web client, only from the console (drop).
• The web client does not use Bluetooth yet, so there is no phone client.
• Transmit power is 2 dBm, a bench setting that reaches across a building, not a town. The
  web client cannot change it yet; a client that speaks the companion protocol can (SET 3), as
  can a build of your own.
• The web client cannot let a new board in once the board has a session: that takes
  accept on the console.
• Keys sit in flash unencrypted. Anyone holding the board can read them.
• One board only. An nRF52 port is next.