From 11ffc7a627586fc9e7d7a31339aadd8b862f994d Mon Sep 17 00:00:00 2001
From: kidfromjupiter <limahaliyana@gmail.com>
Date: Thu, 22 Jan 2026 10:08:55 +0530
Subject: [PATCH] readme improvements

---
 README.md | 30 +++++++++++++++++++++++++-----
 1 file changed, 25 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index b83cfe38..3a1905fd 100644
--- a/README.md
+++ b/README.md
@@ -14,19 +14,20 @@ Bazel is a terrible build system when it does not work and a pretty good one whe
 
 I have tested with various setups:
 
-- Android walkie-talkie example app detects and connects over Bluetooth Classic and Wi-Fi LAN and can share data. Medium upgrade is untested or unclear.
-- Linux to Linux sharing is tested extensively so I can control the advertising and discovery environment.
+- Android walkie-talkie example app detects and connects over Bluetooth Classic and Wi-Fi LAN and can share data. ~~Medium upgrade is untested or unclear.~~
+- Linux to Linux sharing can be tested extensively so I can control the advertising and discovery environment.
 - I do not have access to the Android implementation details.
 - If you enable Quick Share visibility to Everyone on Android and run `sharing/linux` in advertising mode, it appears as a target in the Quick Share menu (promising, but not a full end-to-end validation).
 
-What is tested:
+#### What is tested
 
 - Linux to Linux sharing: advertising, discovery, and data work over Wi-Fi Direct, Wi-Fi Hotspot, Wi-Fi LAN, and Bluetooth Classic.
 - BLE advertising and discovery work, but without a data medium.
 - GATT advertising and discovery work.
-- Android to Linux Nearby Connections work for the same mediums as Linux to Linux above (Bluetooth Classic, Wi-Fi LAN, Wi-Fi Hotspot, Wi-Fi Direct).
+- Android to Linux Nearby Connections work for the same mediums as Linux to Linux above (Bluetooth Classic, Wi-Fi LAN, Wi-Fi Hotspot, Wi-Fi Direct). Testing used https://github.com/kidfromjupiter/nearby-connections-android, which exposes the full Nearby Connections API on Android.
+- Connection initiation succeeds in both directions (Android -> Linux and Linux -> Android) when using the Nearby Connections example apps on Android and Linux. Quick Share still fails.
 
-What is not tested or unknown:
+#### What is not tested or unknown
 
 - Android to Linux Nearby Sharing with Quick Share end-to-end; current status is that it fails during the Quick Share connecting stage.
 
@@ -36,6 +37,24 @@ Debugging tip: when investigating Quick Share failures on Android, this helps:
 adb logcat | grep -Ei 'NearbySharing|NearbyConnections|NeabyMediums'
 ```
 
+## Known issues
+
+### Android to Linux Quick Share connection failure
+
+Observed Android log output when initiating a share from Android to Linux:
+
+```
+I NearbySharing: [NS_AUTH] send-side ConnectionFailure
+01-21 10:49:27.180 24952 14785 I NearbySharing: [ClearcutLog] ESTABLISH_CONNECTION sessionId=8906741495577782802 status: 5 shareTarget: ShareTarget<version: 1, id: 14, deviceName: NoName, fullName: null, imageUri: null, type: LAPTOP, fileAttachmentSize: 0, unredactedFileAttachmentSize: 0, textAttachmentSize: 0, wifiCredentialsAttachmentSize 0, appAttachmentSize: 0, streamAttachmentSize: 0, folderAttachmentSize: 0, isKnown: false, isIncoming: false, groupName: null, action: null, isExternal: false, deviceId: null, hasSharedAccount: false, useCase: 0, modelName: null, isOutgoingQrCodeMatching: false, isSharingOverCloud: false, vendorId: 0> referrer: null durationMillis: 21556
+01-21 10:49:27.181 24952 14355 I NearbySharing: NearbySharing Internal event ConnectFailed(endpointId=NN28, failure=AUTH_FAILURE)
+```
+
+This suggests Android to Linux sharing may require reverse engineering Android Nearby Sharing authentication.
+
+### Wi-Fi Hotspot upgrade failure on Android to Linux
+
+When initiating a connection from Android to Linux, the Wi-Fi Hotspot medium upgrade currently fails.
+
 This is not an officially supported Google product.
 
 ## What is included
@@ -96,6 +115,7 @@ Note: BLE fast advertising is not supported on Linux because Android uses separa
 - Nearby Connections examples:
   - Walkie-talkie: `nearby/connection/walkietalkie`
   - File share: `nearby/connections/file_share`
+- Android Nearby Connections example app (full API exposure): https://github.com/kidfromjupiter/nearby-connections-android
 
 ## Contributing