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.