v0.5.0-alpha.1

The first alpha of 0.5. A board keeps to an airtime budget and tells the phone when a message
waits for it, a leaf that is carried somewhere else finds the relays there, a board with a GPS
knows where it is, and a phone can turn a board off.

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.

Update every board in a network together. Messages, groups and positions pass between this
release and 0.4.0-alpha.1, but routing does not quite: see Updating.

What changed

• An airtime budget (draft/airtime.md).
  Beside the region's own limit, a board spends at most 2% of its time, held for ten minutes, on
  frames it writes, and a relay 7%, held for a minute, on frames it passes on. Its own frames wait
  for the budget, frames passed on that it does not hold are dropped, and acknowledgements always
  go. A message that waits for it shows the phone how long (companion reason 4). Every number is
  provisional.
• Leaves that move (ternmesh/spec#44). A leaf that no longer hears the relay it was attached
  to asks the relays around it with a new solicit frame, which they answer, and re-attaches where
  it is now. Relays list whether each route's destination is a leaf, and wait for a leaf's newer
  sequence number before giving up a route to it.
• A board's own flood may be sent once more when no relay is heard passing it on within
  sixteen airtimes. A busy radio sends it again less often, and one busy all the time not at
  all, as a busy relay passes fewer on. A position to a group starts at two hops, as
  draft/positions.md now has it.
• Satellite receivers (companion protocol version 8). The T-Beam's GPS, V1.0 to V1.2, and
  the Wireless Tracker V1.1's receiver are powered and read; the Tracker V1.0's, whose supply
  turns on the other way, stays off. The node's position is the more recent of the
  receiver's fix and a phone's, and FIX tells every client which. A client can turn the
  receiver off and on. None of these boards has run it yet.
• Turning off from a phone (companion protocol version 9). OFF turns the board off, as
  holding PRG does. Only the board's own button turns it on again.
• Battery empty no longer says a press of PRG turns the board on: below 3.3 V it turns
  straight off again. It turns on again by itself once charged above 3.45 V.

First contact, sessions, messages to one board, group messages, positions and cards are the same
on the air as in 0.4.0-alpha.1.

What was tested, and what was not

CI built every image of this release, for every board and region, and ran the suite on a
computer: the specification's vectors, including the routing draft's for leaves that move and the
airtime draft's, the companion protocol, and a mesh in the simulator.

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

• A board on 0.4.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 spoke companion protocol version 9, and OFF turned it off.

Not tested on a board as part of this release: anything between two boards, so no message,
route, re-attaching leaf or resent flood went over the air between two that both run it; the
airtime budget holding a frame back; satellite receivers, which no board here has; Bluetooth; and
every board other than the Heltec V3. If you have one, what it does when it starts is the report
we most want, and the checklist is in docs/boards.md.

Updating

A Heltec V3 on 0.2.0-alpha.1 or later 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.5.0-alpha.1-app.bin

The apps and ternmesh.org offer the same update once the site
lists this release.

A board on 0.4.0-alpha.1 reads the routes this release announces to leaves as far dearer than
they are, since it does not know the bit that marks a leaf, and it does not answer a leaf asking
after relays. Update every board in a network, and routes form as they should.

For a new node, or to start a board afresh with a new address, write the full image at 0x0:
it replaces whatever is on the board.

tern-<board>-us915-0.5.0-alpha.1.bin	United States, Canada, Mexico, Brazil, Argentina, Peru
tern-<board>-eu868-0.5.0-alpha.1.bin	Europe, UK, Ukraine, South Africa: 10% of any hour
tern-<board>-au915-0.5.0-alpha.1.bin	Australia
tern-<board>-nz915-0.5.0-alpha.1.bin	New Zealand
tern-<board>-cl915-0.5.0-alpha.1.bin	Chile
tern-<board>-my919-0.5.0-alpha.1.bin	Malaysia
tern-<board>-th920-0.5.0-alpha.1.bin	Thailand: 17 dBm radiated or more, 10% of any hour
tern-<board>-ru868-0.5.0-alpha.1.bin	Russia: at most 10% of any hour
tern-<board>-kz863-0.5.0-alpha.1.bin	Kazakhstan: not within airports

<board> is the board's name in docs/boards.md, such as heltec-v3. An
nRF52840 board takes tern-<board>-<region>-0.5.0-alpha.1.uf2: press RST twice, and copy the
file onto the drive 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, or turn
  it off, 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 join code is a group's secret. Share it as you would the group itself.
• A card is public. Its name goes to every board within two hops, unsealed.
• The rules are yours to keep. The regions follow each country's rules as written, but
  nothing here is certified, and whoever operates a radio answers for it.

What is still not in it

• No message to everyone. A group is those who were invited or given its code; 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, and TH920 images at 14 dBm.
• No region yet for India, Japan, Korea, Singapore, Vietnam, Indonesia or Hong Kong, whose
  rules need features the specification does not have yet.
• The nRF52840 boards have no satellite receiver yet.