<div align="center">
  <img src="HConnect/Assets.xcassets/AppIcon.appiconset/1024.png" alt="HConnect Logo" width="200"/>
  <h1 style="font-weight: 700; font-size: 4em; margin: 0; padding-top: 0;">HConnect Mac</h1>
  <p>
  HConnect Mac is a KDE Connect compatible application for macOS — the desktop companion to <b>HConnect</b> for Android. It allows better integration between your phones, desktops and tablets.
  </p>
</div>

---

## About this fork

HConnect Mac is a fork of [sannidhyaroy/Soduto](https://github.com/sannidhyaroy/Soduto) (the actively maintained modernization of [the original Soduto](https://github.com/soduto/Soduto) by Giedrius Stanevičius — SwiftNIO transport, KDE Connect protocol v8, mDNS discovery, Swift Package Manager), rebranded and maintained as the macOS counterpart to HConnect for Android.

- Upstream remote: `sannidhyaroy` → `https://github.com/sannidhyaroy/Soduto` (pull fixes from `nightly`)
- Bundle identifier prefix: `mm.technomation.*` (matches HConnect Android's `mm.technomation.hconnect`)
- Stack: SwiftNIO + NIOSSL, Citadel SFTP, swift-certificates, Sparkle via SPM (KDE Connect protocol v8)
- License: GPL, same as upstream — see [LICENSE](LICENSE)

For gaps against HConnect (Android) and the roadmap for closing them, see [FEATURE_GAPS.md](FEATURE_GAPS.md). For the BLE backend build/test notes, see [BLE_TESTING.md](BLE_TESTING.md).

---
## **Navigation**
- [Features](#features)
- [Building](#building)
- [Debugging](#debugging)
- [Limitations](#limitations)
- [Workarounds](#workarounds)
- [License](#license)
---
## Features

HConnect Mac implements the following KDE Connect plugin features (compatible with any KDE Connect device):

### Notifications
- [x] Receive — Mirror remote device notifications on macOS (with automatic OTP copying)
- [ ] Send — Send macOS notifications to remote devices

### Clipboard
- [x] Receive — Receive clipboard content from remote devices
- [x] Send — Send macOS clipboard content to remote devices

### File Sharing
- [x] Receive — Receive shared files, links, and text from remote devices (files are saved in the Downloads folder)
- [x] Send — Share files, links, and text to remote devices via Share extension, drag and drop to menu bar, or `Send Files` option
- [x] Browse storage — Access remote device filesystem via SFTP

### Battery Status
- [x] Receive — View remote device battery level and charging status
- [x] Send — Send macOS battery status to remote devices

### Media Control (MPRIS)
- [x] Receive — Control remote device music/video playback from macOS Control Center and Now Playing Module (experimental)
- [ ] Send — Control macOS music/video playback from remote devices

### Telephony
- [x] Receive — View incoming call and SMS notifications from remote devices

### SMS Window
- [ ] Receive — View SMS of remote devices
- [x] Send — Send SMS from macOS

### Remote Input
- [x] Receive — Use remote device as keyboard and touchpad for macOS
- [x] Send — Use macOS to control remote device input (experimental)

### Ping
- [x] Receive — Receive ping messages from remote devices
- [x] Send — Send ping messages to remote devices

### Run Commands
- [x] Receive — Execute macOS commands from remote devices
- [ ] Send — Execute predefined commands on remote devices

### Find My Device
- [x] Receive — Make macOS play an alarm sound to locate it
- [x] Send — Make remote device play an alarm sound to locate it

### Connectivity Report
- [x] Receive — Monitor remote device network connectivity status

### Presentation Remote
- [x] Receive — Use remote device as presentation remote for macOS
- [ ] Send — Use macOS as presentation remote for remote device

### Contacts
- [x] Receive — Synchronize contacts between macOS and remote devices

### Bluetooth LE (HConnect extension)
- [x] Discover and link to HConnect Android devices over BLE when no shared network is available (control channel only; see [BLE_TESTING.md](BLE_TESTING.md))

For the complete list of KDE Connect features and documentation, visit the [official KDE Connect Wiki](https://userbase.kde.org/KDEConnect).

---
## Building

Requires a Mac with Xcode.

- Open project `HConnect.xcodeproj` with Xcode.
  - Swift Package dependencies (`swift-certificates`, `SwiftNIO`, `NIOSSL`, `NIOSSH`, `Citadel`, `Sparkle`, etc.) will resolve automatically on first build.
- Select `HConnect` as Target. Go to `Signing & Capabilities` and under the `Signing` section, ensure your appropriate `Team` is selected.
- Make sure you have the same `App Group key` for `HConnect Share` and also verify that the same `Team` is selected for each target.
- Build target `HConnect`

---
## Debugging

HConnect uses Apple's Unified Logging system (`os.Logger`). Logs are organized by subsystem and categories:

| Target | Subsystem | Categories |
|--------|-----------|------------|
| **HConnect** | `mm.technomation.HConnect` | `general`, `network`, `device`, `config`, `services`, `ui` |
| **HConnect Files** | `mm.technomation.HConnect-Files` | `general`, `filesystem`, `ui` |
| **HConnect Share** | `mm.technomation.HConnect.HConnect-Share` | `general`, `sharing`, `ui` |

### View logs in real-time:
```bash
# Show all messages (debug, info, notice, error) for HConnect
log stream --predicate 'subsystem == "mm.technomation.HConnect"' --level debug

# Show all messages from ALL HConnect components
log stream --predicate 'subsystem BEGINSWITH "mm.technomation.HConnect"' --level debug
```

The `--level debug` flag shows messages at debug level **and above** (info, notice, error, fault).

### Enable debug message persistence:
By default, debug messages are only kept in memory and not saved to disk. To persist them:

```bash
sudo log config --subsystem mm.technomation.HConnect --mode level:debug
```

This allows you to view debug messages in Console.app after they occur. Revert with `--mode level:default` when done.

### View logs in the Console:
- Open `Console.app`
- In the search field, enter the subsystem for the target you want to view (e.g. `subsystem:mm.technomation.HConnect`)
- Filter by category for targeted debugging: `category:network`, `category:services`, `category:device`, etc.
- Enable "Include Debug Messages" in the Action menu to see debug-level logs

**Warning:** Debug logging may include sensitive data (clipboard contents, passwords). Only enable its persistence during debugging and revert to default when done.

---
## Limitations

#### Clipboard Sync (Android 10+)
Google introduced privacy restrictions on Android 10 and higher that prevent apps from accessing clipboard data unless the app is the default input method editor (IME) or is currently in focus. This affects seamless clipboard sync between HConnect and HConnect Mac. Your clipboard will automatically sync to your other devices when you copy something on your mac, however you will have to manually tap on `Send Clipboard` in the HConnect app every time you want to sync your Android's clipboard to your mac.

#### Storage Access (Android 11+)
On Android 11 and higher, you may not be able to add the root location of your Internal Storage or your Download folder to HConnect's `Filesystem expose` locations due to Google's privacy changes.

#### Sensitive Notification Content (Android 15+)
On Android 15 and higher, the system hides sensitive notification content (such as passwords, OTPs, and other sensitive information) from applications by default. This means HConnect Mac will display "Sensitive notification content hidden" instead of the actual content. HConnect will not receive sensitive notifications unless you explicitly grant the `RECEIVE_SENSITIVE_NOTIFICATIONS` permission (see workarounds below).

---
## Workarounds

#### Clipboard Sync (Android 10+)
If you have `Riru` or `Zygisk`, you can bypass the clipboard restriction on Android 10 or higher by using [Kr328's Clipboard Whitelist](https://github.com/Kr328/Riru-ClipboardWhitelist) module and then tick your KDE Connect-based app from the `Clipboard Whitelist` app. If you're on Android 13 and the module isn't working for you, try [Xposed Clipboard Whitelist](https://github.com/GamerGirlandCo/xposed-clipboard-whitelist) (remember to select `System Framework` for the module scope).

#### Storage Access (Android 11+)
[NoStorageRestrict](https://github.com/Xposed-Modules-Repo/com.github.dan.nostoragerestrict) is an `Xposed Module` that removes the restriction when selecting folders (like Internal Storage, Android, Download, data, obb) through file manager on Android 11 and higher. There is a [Magisk module](https://github.com/DanGLES3/NoStorageRestrict) for this as well.

#### Sensitive Notification Content (Android 15+)
Grant HConnect the `RECEIVE_SENSITIVE_NOTIFICATIONS` permission using ADB:

```bash
adb shell cmd appops set --user 0 mm.technomation.hconnect RECEIVE_SENSITIVE_NOTIFICATIONS allow
```

If you see `java.lang.SecurityException: uid 2000 does not have android.permission.MANAGE_APP_OPS_MODES`, enable "Disable permission monitoring" in Developer Options, reboot, and run the command again. Reboot once more for the change to take effect.

---
## Documentation & Resources

For comprehensive information about KDE Connect features, limitations, configuration, and troubleshooting across all platforms, visit the [official KDE Connect Wiki](https://userbase.kde.org/KDEConnect). The upstream repository's [protocol.md](protocol.md) documents the KDE Connect protocol as implemented here.

---
## License

HConnect Mac is licensed under the [GNU General Public License v3.0](LICENSE), the same license as Soduto, from which it is derived.
