1 files changed, 67 insertions, 0 deletions
diff --git a/desktop/modules/sonix/README.md b/desktop/modules/sonix/README.md
new file mode 100644
index 0000000..945b62e
--- /dev/null
+++ b/desktop/modules/sonix/README.md
@@ -0,0 +1,67 @@
+# sonix
+
+A HiBy R1 running [Sonix Player](https://github.com/Jepl4r/sonix-player),
+over the LAN: an icon and controls panel in the island's status pill, a
+drawer tile and page, and a boot logo editor in the settings window, under
+its own sidebar group "HiBy R1".
+
+## The player's two servers
+
+- **SonixLink**, HTTP on port 7800, no authentication: state, commands,
+  covers, the library. Switched on from the player's control centre.
+  Anyone on the network can drive the player while it is on.
+- **Wi-Fi transfer**, HTTP on port 80: the card's file server. It runs only
+  while its page is open on the player; leaving the page stops it. Used
+  only by the boot logo upload.
+
+## Presence
+
+SonixLink broadcasts `SONIXLINK1 <ip> <port> <name>` to UDP 7801 every 2s.
+`sonix-beacon.py` relays it to stdout (QML has no UDP socket) and
+`desktop/Sonix.qml` reads it: present while beacons arrive, gone 6s after
+the last. The address follows the beacon, so DHCP changes need nothing.
+
+## Polling
+
+`/api/state` is read every second while a view holds the service: the
+island panel, the drawer tile, the drawer page. Nothing is polled
+otherwise, and `/api/bye` is sent when the last view lets go, so the player
+stops counting a client.
+
+## Notes
+
+SonixLink's `bitrate` is in bits per second; the panel shows kbps. The
+heart in the panel sends the `favourite` command (path, value 1 or 0).
+
+## Drawer page
+
+Device: name, address, battery, the player's accent, the library and a
+Rescan, what is playing, a link to Wi-Fi transfer and to the boot logo
+page. Playlists: play, open, remove a track, new names. Folders: browse,
+play a folder or a file, add either to a playlist; folder rows carry
+"folder" as their second line. The tab starts at the card root by browsing
+with an empty path (the player answers `path=/` with plain text "outside
+the card").
+
+SonixLink has no rename, delete or reorder for playlists, and makes a
+playlist only by adding a track to a new name. The player has rename and
+delete internally but does not expose them; the `.m3u` files on the card
+are backups, not the playlists. Do those on the player. `play_all` refuses
+a folder, so a folder plays as its first file with the folder as the list.
+
+## Boot logo
+
+The page is in the settings window, under the "HiBy R1" group. A 480x800
+scene: the picture, panned and zoomed, and the text in one of four faces
+(Bungee with its Inline layer, Major Mono Display, Michroma, Audiowide; SIL
+OFL, in `fonts/`) in two colours: the six player accents, white, black, or
+the udt accent. Save writes `bootlogo-<stamp>.png` and
+`bootlogo-<stamp>-mask.png`, the text on transparency, to the output folder.
+Upload saves, then sends the PNG to `Bootlogo/` on the card through Wi-Fi
+transfer, waiting up to 60s for it to be opened on the player. The logo is
+then picked on the player: Settings > Appearance > Boot logo.
+
+## Tests
+
+    node desktop/modules/sonix/test_sonix.js
+    /usr/bin/python3 desktop/modules/sonix/test_sonix_beacon.py