Troubleshooting - solum-signage-system/solum-signage-example GitHub Wiki

Troubleshooting

This section compiles common issues you might encounter while working with the SoluM Signage Examples Android project and their solutions.

1. Project Build Errors in Android Studio

Problem: Android Studio fails to build the project, showing errors related to dependencies or Gradle.

Possible Causes & Solutions:

  • GitHub Personal Access Token (PAT) Not Configured or Incorrect:
    • Reason: The project might be unable to download SoluM's Device API packages from GitHub if your settings.gradle.kts is not correctly configured with your username and PAT, or if the PAT is expired/invalid.
    • Solution: Double-check steps 1 and 2 in the Installation Guide. Ensure your PAT has the necessary permissions (e.g., read:packages).
  • Gradle Sync Issues:
    • Reason: Network problems, corrupted Gradle cache, or incorrect Gradle version.
    • Solution:
      1. Ensure you have a stable internet connection.
      2. Try File > Invalidate Caches / Restart... in Android Studio.
      3. Check the build.gradle (Module: app) file for any dependency conflicts.
  • Android SDK / Tooling Issues:
    • Reason: Missing or outdated Android SDK components.
    • Solution: Open Tools > SDK Manager in Android Studio and ensure all required SDK Platforms and SDK Tools are installed and up-to-date.

2. Application Installation Failure on Device

Problem: The APK file fails to install on the SoluM Signage device via USB or CMS PlayWizard.

Possible Causes & Solutions:

  • APK File Corruption:
    • Reason: The APK file might be incomplete or corrupted during generation or transfer.
    • Solution: Rebuild the APK in Android Studio and copy it again to the USB stick.
  • Insufficient Storage:
    • Reason: The device might not have enough free storage space for the application.
    • Solution: Check the device's storage and free up space if necessary.
  • App Signature Conflict:
    • Reason: If an older version of the app with a different signature is already installed, a new installation might fail.
    • Solution: Uninstall any previous versions of the "SoluM Signage example" app from the device before attempting a new installation.

3. Device API Calls Not Working

Problem: Buttons or actions in the app related to SoluM's Device API (e.g., setting brightness, rebooting) do not work as expected.

Possible Causes & Solutions:

  • Missing Device API Libraries:
    • Reason: The device API packages might not have been correctly imported or linked during the build process (often related to PAT issues).
    • Solution: Ensure the project built successfully without dependency errors. Recheck settings.gradle.kts and PAT.
  • Insufficient Permissions:
    • Reason: The application might lack necessary Android permissions to perform certain device operations.
    • Solution:
      1. Check the AndroidManifest.xml file for required permissions (e.g., android.permission.REBOOT).
      2. Ensure the app is granted runtime permissions if required (for Android 6.0+).
  • Device Compatibility:
    • Reason: The specific Device API features might only be available on certain SoluM device models or firmware versions.
    • Solution: Consult SoluM's official documentation for the Device API and ensure your device's firmware is compatible.
  • Device Admin Privileges:
    • Reason: Some sensitive device operations (like reboot) might require the app to be set as a Device Administrator.
    • Solution: Check if the app needs to be enabled as a Device Administrator on the SoluM device (Settings > Security > Device admin apps).

4. App Crashing or Freezing

Problem: The application crashes unexpectedly or becomes unresponsive during use.

Possible Causes & Solutions:

  • Unhandled Exceptions in Code:
    • Reason: Errors in the application's Kotlin/Java code that are not properly handled.
    • Solution: Use Android Studio's Logcat (View > Tool Windows > Logcat) to view crash logs. The stack trace will point to the specific line of code causing the crash.
  • Resource Exhaustion:
    • Reason: The app might be consuming too much memory or CPU, especially if processing large media files inefficiently.
    • Solution: Optimize code for memory usage, ensure efficient handling of large files, and check for memory leaks.