NAME
     aether - ther mesh network protocol over /net

SYNOPSIS
     /net/aether/clone
     /net/aether/addr
     /net/aether/status
     /net/aether/stats
     /net/aether/phy
     /net/aether/n/ctl
     /net/aether/n/data
     /net/aether/n/local
     /net/aether/n/remote
     /net/aether/n/status

DESCRIPTION
     Aether is a connectionless, reliable datagram network presented as a Plan
     9 ip(3)-style protocol directory under /net.  It is reached by longest-
     prefix server lookup alongside /net/tcp and /net/wifi, and is independent
     of the radio underneath: the same file interface is served over LoRa or
     IEEE 802.15.4 (see PROVIDERS below).  A conforming consumer cannot tell
     which is in use.

     A node is named by a 6-byte address rendered as lowercase, zero-padded,
     colon-separated hex, aa:bb:cc:dd:ee:ff.  The address is an ther-overlay
     identifier, mapped by each provider to its radio's native addressing; a
     non-6-byte PHY (e.g. IEEE 802.15.4, 2-byte short or 8-byte EUI-64) maps
     to a 6-byte ther ID.  The dial string form is aether!addr.  Delivery is
     reliable, in order, and de-duplicated; messages are framed (one write is
     one datagram, one read is one datagram).  Fragmentation and reassembly
     happen below the file interface and are invisible to readers and writers.

   Connections
     A conversation is opened by reading clone, which allocates a free slot n,
     rebinds the open fid to n/ctl (Plan 9 clone semantics), and returns the
     decimal slot number.  The conversation persists until hangup so a script
     may use the idiom

          n=`{cat /net/aether/clone}
          echo connect aa:bb:cc:dd:ee:ff >/net/aether/$n/ctl
          rw /net/aether/$n/data
          echo hangup >/net/aether/$n/ctl

     Each conversation directory holds these files.

     ctl  Write one command (below).  A read returns the slot number.

     data Write a datagram; read a datagram.  Reads block until a datagram
          arrives or the conversation hangs up (hangup wakes a blocked reader
          with a 0-length read, i.e. end of file).  Datagram boundaries are
          preserved; the offset is ignored.

     local
          The local address.

     remote
          The peer address, or empty if the conversation is unbound.

     status
          One of connected aether!addr reliable, announced, or unconnected.

   Ctl commands
     connect addr
          Active open: bind the conversation to one peer.  data writes go to
          that peer with no prefix; reads receive only from it, no prefix.

          The all-ones address ff:ff:ff:ff:ff:ff is special: it joins the
          broadcast party line -- a connectionless, best-effort class (the chat
          lobby).  data writes go out best-effort to all peers (no ARQ, no
          fragmentation); reads are source-prefixed ([src][payload]) and
          receive any peer's broadcast.  Directed unicast stays reliable.

     announce
          Passive open: receive datagrams from any peer.  A data read is
          prefixed with the 6-byte source address; a data write is prefixed
          with the 6-byte destination address, so a server replies to whoever
          it just heard from.  This is the udp(3) datagram-server idiom.

     hangup
          Unbind the conversation, wake a blocked reader with end of file, and
          free the slot.

     Unknown verbs, or connect and announce on an already-bound conversation,
     return an error.  The verbs port, unreliable, and keepalive are reserved
     (see BUGS).

   Top-level files
     addr This node's address.

     status
          A summary line: active versus maximum conversations, and the
          neighbour count.  Leading active/max is parseable; the remainder is
          advisory.

     stats

     phy  Provider-specific (optional).  On the LoRa provider, stats reads rx
          tx rssi snr and phy reads and accepts one key value per write (sf,
          bw in kHz, cr as the 4/x denominator, cad on/off, pwr in dBm).  PHY
          tuning lives behind the file interface, never in it; both ends of a
          link must agree.

   9P over aether
     The service is reliable, ordered, message-framed, and without flow
     control -- the shape of IL (il(3)), which was built to carry 9P.  A 9P
     session therefore rides /net/aether directly, one 9P message per
     datagram.  A mounter (active) does connect  peer and writes T-messages,
     reads R-messages, no prefix.  An exporter (passive) does announce and
     reads [src][T], replies [src][R].  The 9P msize is negotiated less than
     or equal to the reassembly ceiling (MAX_MSG, 512 in the reference); small
     is fine -- the radio is slow.

PROVIDERS
     A provider implements this file interface over one radio.  The interface
     is the contract; the radio is swappable.

     LoRa Local server in the deck firmware over the on-board SX1262, on the
          ther mesh reliable engine.  Implemented.

     IEEE 802.15.4
          Planned; rides a 15.4 radio (ESP32-C6 or nRF52840).  Not yet
          implemented.

FILES
     /net/aether
          the protocol directory

     /dev/aether
          node-level state -- address, peers, routes -- distinct from this
          network interface

SOURCE
     src/dev_aether_net.c
          the LoRa reference server (gated on CONFIG_AETHER_MESH)

     src/transport_aether.c
          the 9P transport that rides a conversation

     zephyr/net/aether_reliable.h
          the reliable-datagram engine

SEE ALSO
     dial(1), achat(1), aexport(1), who(1), chat(1)

     The Plan 9 pages this one is written against -- ip(3), udp(3), il(3),
     dial(2) -- are in Plan 9's manual, not this one.

     NET_AETHER_SPEC.md -- design notes: IL-not-TCP rationale, the gateway
     L2CAP binding, and the reserved surface.

BUGS
     Per-peer multiplexing (port), a best-effort (unreliable) class, a
     neighbour table as files, and keepalive are reserved but unimplemented.

     The IEEE 802.15.4 provider does not exist yet.

     The kernel-side fast receive path used by the in-firmware 9P client
     (aether_net_set_krecv) is a provider-private optimisation, not part of
     the file contract; a mounted-remote provider falls back to blocking data
     reads.

FRST Computer                                                        AETHER(3)
