# kith

> A small e-paper handheld for friend groups at festivals, camps and off-grid
> gatherings: one friend, an arrow and a distance over a LoRa mesh, with UWB
> ranging for the last hundred metres. No feed, no badges, no lights. This site
> is an idea page with a working mock of the device in the browser; there is no
> hardware yet.

## The idea

- Calm by design: the default screen is one friend + bearing + distance and
  nothing else; friends drop off the screen once you can see them; the haptic
  fires for direct messages only; no feeds, unread counts, badges or LEDs;
  messages are short (60 characters) and ephemeral (an hour); voice notes live
  in threads and play only when asked; a magnetic clip or lanyard so the device
  hangs face out and is glanced at like a watch; a dancer is not interrupted
  (the accelerometer detects dancing: keys lock, direct messages wait, one
  tap is paid when the song ends, and friends see "dancing" in place of a
  distance).
- Activity: the LIS2DW12 accelerometer alone (no gyroscope). Still, walking
  or dancing from a five-second window: dancing is the walking band (1.3-3.8
  Hz) with about three times the energy and GPS speed near zero, sustained
  for twenty seconds; a beacon carries it as one flag bit.
- Hardware (proposed): ESP32-S3 (MeshCore T-Deck port as the base), SX1262
  LoRa, DW3000 UWB, QMC5883L magnetometer + LIS2DW12 accelerometer for a
  tilt-compensated heading, ES8311 codec + NS4150 amp (piezo fallback), 2.9"
  296x128 e-paper, 35-key tact-dome keyboard with a round push-to-talk key,
  one haptic motor, 2000 mAh LiPo, USB-C. Rough BOM $38-45 at 100 units,
  about $27 without UWB, $25-30 at 1k+.
- The screen question: e-paper (2.9" 296x128, ~0.3 s partial refresh with
  ghosting, ~1.4 s full refresh with flashes, holds an image for nothing) or
  a Sharp memory LCD (2.7" 400x240, instant line updates, no ghost or flash,
  silver background, ~50 uW to hold an image, ~$15 more per unit, and the
  calm has to be enforced by the firmware rather than the glass). Both are
  modelled; the landing page runs them side by side in the same scene and
  /sim has a screen switch.
- The keyboard question: the 35-key slab, or a 4.2" 400x300 touch e-paper
  card with one side key (push-to-talk). On the card nothing is typed after
  setup: messages are the five canned lines as chips and voice notes; the
  arrow is the next-friend control, the name opens the thread, friends rows
  walk toward someone or open their thread; a swipe changes friend; setup
  uses an on-screen keyboard once. Both are live side by side on the landing
  page and /sim has a form switch.
- Open questions: whether UWB earns ~30% of the BOM versus GPS coordinates
  shared over the mesh; single-antenna ranging gives distance, not bearing
  (the arrow's direction comes from beacons + compass); 868 vs 915 MHz;
  the lanyard's own ~1 Hz swing in the activity detector;
  antenna; e-paper at night; speaker magnet vs magnetometer; a keyboard in a
  pocket.

## Pages

- [/](https://kith.proc.io/): the idea, a live mock device, a gallery of its
  screens, the calm rules, hardware and BOM, open questions.
- [/sim](https://kith.proc.io/sim): the interactive mock. A map of friends you
  can drag, the device one of them holds (click keys, or type with the device
  focused), a UWB on/off switch, a crowd slider, three scenes.

## The mock

- The device is modelled in TypeScript (kith/web/src/device/firmware.ts), not
  compiled firmware; its cousin posse (https://posse.proc.io) runs real
  firmware in wasm. The e-paper panel is modelled with real timing: partial
  refresh ~320 ms with ghosting, a full refresh (three flashes, ~1.4 s) every
  twelve partials, never faster than one refresh per 0.9 s, and the firmware
  only refreshes when a quantised view changes.
- The world (kith/web/src/device/world.ts) moves people, delivers LoRa
  packets with distance- and crowd-dependent loss and airtime, gives each
  device GPS with a few metres of wobble, a compass, and UWB ranges to
  people within ~90 m.
- Keys: space = next friend, enter = open thread, up/down = friends list,
  back = settings (from the glance) or leave; type to write to the friend on
  screen; hold the round key to record a voice note, tap it to play one.
- The display policy is model-checked in TLA+ (kith/specs/CalmGlance.tla):
  one friend on screen, never one in sight, someone on screen whenever there
  is someone to walk toward, tap only for a direct message, messages expire.

## Notes for agents

- Everything runs client side. There is no API and no account.
- kith is always written in lowercase.
- An idea from Infinite Logic PBC (https://infinitelogic.org).