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.