BasicSync: A simple app for running Syncthing on Android

BasicSync is a straightforward application designed to facilitate the operation of Syncthing on Android devices. The developer has purposefully maintained BasicSync's simplicity to ensure easy upkeep and timely updates. Its functionality is limited to managing the execution of Syncthing; the comprehensive configuration of the app is carried out through Syncthing's web interface.

To obtain the most recent version of BasicSync, one must navigate to the releases page. For added security, it is recommended to verify the digital signature, as detailed in the app's documentation. Upon installation, BasicSync requires permissions to be granted and the appropriate run conditions to be set. Once these prerequisites are met, users can then access the Syncthing web interface to customize the application according to their preferences.

By default, BasicSync operates in automatic mode, initiating and terminating Syncthing in accordance with the user-defined conditions. However, this behavior can be altered by switching to manual mode via BasicSync's notification system. This adjustment enables users to manually control the operation of Syncthing as they see fit.

Syncthing communicates on the loopback interface by default, accessible at 127.0.0.1:8384. BasicSync attempts to utilize the same port upon each startup. If a conflict arises, it automatically selects a new random port. The present port number can be viewed in the Web UI under Actions, then Settings, and finally GUI. For enhanced security, both HTTPS and basic authentication are enforced automatically upon Syncthing's initiation.

The password for basic authentication is the API token, which BasicSync updates to match the API token upon each start.

In the case of GrapheneOS users, the application supports an alternative method of file access through OS-level storage scopes, granting direct file access without the constraints imposed by Android's storage access framework.

BasicSync offers an alternative to direct file access via Android's storage access framework (SAF), limiting permissions so that Syncthing can only access predefined folders rather than the entire internal and external storage. Nevertheless, it is generally advised to utilize direct file access as it is less prone to inefficiencies.

Despite the limitations of SAF, BasicSync implements caching mechanisms for directory listings and file metadata, albeit at the expense of reduced performance compared to direct file access. Additionally, SAF does not provide specific watcher events, necessitating Syncthing to rescan folders instead of merely accessing individual files.

Despite BasicSync's efforts to minimize the chances of file naming conflicts when using SAF, there remains a higher probability of encountering unexpected sync errors. In such instances, it is advisable to wait for five minutes for BasicSync's caches to expire and subsequently trigger a rescan of the folder from Syncthing's web interface.

It is important to note that SAF support is a BasicSync feature and not a feature of Syncthing itself. When exporting a configuration from BasicSync and importing it into another app, folders utilizing SAF will not function correctly. For developers working on other Syncthing applications, it is essential to be aware of BasicSync's custom filesystem scheme.

When the "Allow remote control" setting is activated, BasicSync permits other applications to control Syncthing's operation through Android's broadcast mechanism. Supported broadcast actions mirror the functionality of BasicSync's notification buttons. These broadcasts can be transmitted via adb, for instance, using the command "adb sendtextmessage -e com.basic.sync.action start".

Furthermore, BasicSync provides rudimentary support for Android TV, albeit with certain limitations. The user interface remains consistent with that of phone and tablet devices, allowing access to most functionality using the TV remote's arrow keys, including the Syncthing web interface. However, Android TV lacks several key features such as importing and exporting configuration files, saving logs via debug mode, and viewing BasicSync's persistent notification due to the absence of DocumentsUI (the system file manager and file picker) in Android TV.

To overcome the inability to disable battery optimizations on Android TV, which is essential for Syncthing to run reliably in the background, users must employ adb to grant the SYSTEM_EXEMPT_FROM_DISMISSIBLE_NOTIFICATIONS appops permission. Additionally, users have the option to disable the persistent notification from Android's settings by turning off the "Persistent notification" notification channels for BasicSync.

Despite the notification's absence, Syncthing will continue to operate normally as long as the overall notification permission remains granted. Lastly, it is crucial to acknowledge that Android 17 no longer permits apps to communicate with each other over localhost when running in different user profiles or instances, affecting BasicSync's functionality in these scenarios.