Merge pull request #80 from usetrmnl/76-byos_hanami-compatibility

[ADDED] BYOS Hanami server compatibility

Author: hossain-khan

app/src/main/java/ink/trmnl/android/data/TrmnlDeviceConfigDataStore.kt

@@ -52,6 +52,7 @@ class TrmnlDeviceConfigDataStore
             private val API_BASE_URL_KEY = stringPreferencesKey("api_base_url")
             private val REFRESH_RATE_SEC_KEY = longPreferencesKey("refresh_rate_seconds")
             private val CONFIG_JSON_KEY = stringPreferencesKey("config_json")
+            private val DEVICE_MAC_ID_KEY = stringPreferencesKey("device_mac_id")
         }
 
         private val deviceTypeAdapter = moshi.adapter(TrmnlDeviceType::class.java)
@@ -96,6 +97,14 @@ class TrmnlDeviceConfigDataStore
                 preferences[REFRESH_RATE_SEC_KEY]
             }
 
+        /**
+         * Gets the device MAC address as a Flow
+         */
+        val deviceMacIdFlow: Flow<String?> =
+            context.deviceConfigStore.data.map { preferences ->
+                preferences[DEVICE_MAC_ID_KEY]
+            }
+
         /**
          * Gets the complete device config as a Flow
          */
@@ -123,12 +132,14 @@ class TrmnlDeviceConfigDataStore
                     val token = preferences[ACCESS_TOKEN_KEY]
                     val url = preferences[API_BASE_URL_KEY] ?: TRMNL_API_SERVER_BASE_URL
                     val refreshRate = preferences[REFRESH_RATE_SEC_KEY] ?: DEFAULT_REFRESH_INTERVAL_SEC
+                    val deviceMacId = preferences[DEVICE_MAC_ID_KEY]
 
                     if (token != null) {
                         TrmnlDeviceConfig(
                             type = type,
                             apiBaseUrl = url,
                             apiAccessToken = token,
+                            deviceMacId = deviceMacId,
                             refreshRateSecs = refreshRate,
                         )
                     } else {
@@ -152,6 +163,11 @@ class TrmnlDeviceConfigDataStore
                     preferences[ACCESS_TOKEN_KEY] = config.apiAccessToken
                     preferences[API_BASE_URL_KEY] = config.apiBaseUrl
                     preferences[REFRESH_RATE_SEC_KEY] = config.refreshRateSecs
+
+                    // Save device ID if available
+                    config.deviceMacId?.let { deviceMacId ->
+                        preferences[DEVICE_MAC_ID_KEY] = deviceMacId
+                    }
                 }
             } catch (e: Exception) {
                 Timber.tag(TAG).e(e, "Failed to save device config")
@@ -194,6 +210,19 @@ class TrmnlDeviceConfigDataStore
             }
         }
 
+        /**
+         * Saves the device ID (MAC address)
+         */
+        suspend fun saveDeviceMacId(deviceMacId: String?) {
+            context.deviceConfigStore.edit { preferences ->
+                if (deviceMacId != null) {
+                    preferences[DEVICE_MAC_ID_KEY] = deviceMacId
+                } else {
+                    preferences.remove(DEVICE_MAC_ID_KEY)
+                }
+            }
+        }
+
         /**
          * Checks if a token is already set
          */

app/src/main/java/ink/trmnl/android/data/TrmnlDisplayRepository.kt

@@ -53,6 +53,11 @@ class TrmnlDisplayRepository
                     .getNextDisplayData(
                         fullApiUrl = constructApiUrl(trmnlDeviceConfig.apiBaseUrl, NEXT_PLAYLIST_SCREEN_API_PATH),
                         accessToken = trmnlDeviceConfig.apiAccessToken,
+                        // Send device MAC ID if available (used for BYOS service)
+                        deviceMacId = trmnlDeviceConfig.deviceMacId,
+                        // TEMP FIX: Use Base64 encoding to avoid relative path issue
+                        // See https://github.com/usetrmnl/trmnl-android/issues/76#issuecomment-2980018109
+                        useBase64 = trmnlDeviceConfig.type == TrmnlDeviceType.BYOS,
                     )
 
             when (result) {

app/src/main/java/ink/trmnl/android/model/TrmnlDeviceConfig.kt

@@ -19,5 +19,9 @@ data class TrmnlDeviceConfig constructor(
     val type: TrmnlDeviceType,
     val apiBaseUrl: String,
     val apiAccessToken: String,
+    /**
+     * Device MAC address for API authentication, usually used by BYOS servers.
+     */
+    val deviceMacId: String? = null,
     val refreshRateSecs: Long = DEFAULT_REFRESH_INTERVAL_SEC,
 )

app/src/main/java/ink/trmnl/android/network/TrmnlApiService.kt

@@ -41,12 +41,19 @@ interface TrmnlApiService {
      *
      * NOTE: This API always loads the next plugin image from the playlist.
      *
+     * @param fullApiUrl The complete API URL to call
+     * @param accessToken The device's API key (required)
+     * @param deviceMacId The device's MAC address (optional)
+     * @param useBase64 Whether to request Base64-encoded image data (optional)
+     *
      * @see getCurrentDisplayData
      */
     @GET
     suspend fun getNextDisplayData(
         @Url fullApiUrl: String,
         @Header("access-token") accessToken: String,
+        @Header("ID") deviceMacId: String? = null,
+        @Header("BASE64") useBase64: Boolean? = null,
     ): ApiResult<TrmnlDisplayResponse, Unit>
 
     /**

app/src/main/java/ink/trmnl/android/network/model/TrmnlDisplayResponse.kt

@@ -2,6 +2,7 @@ package ink.trmnl.android.network.model
 
 import com.squareup.moshi.Json
 import com.squareup.moshi.JsonClass
+import ink.trmnl.android.util.HTTP_NONE
 
 /**
  * Data class representing the response from the TRMNL API for display data.
@@ -34,10 +35,34 @@ import com.squareup.moshi.JsonClass
  * ```json
  * {"status":500,"error":"Device not found","reset_firmware":true}
  * ```
+ *
+ * Sample response from BYOS Hanami server:
+ * ```json
+ * {
+ *   "filename": "demo.bmp",
+ *   "firmware_url": "http://localhost:2443/assets/firmware/1.4.8.bin",
+ *   "image_url": "https://localhost:2443/assets/screens/A1B2C3D4E5F6/demo.bmp",
+ *   "image_url_timeout": 0,
+ *   "refresh_rate": 130,
+ *   "reset_firmware": false,
+ *   "special_function": "sleep",
+ *   "update_firmware": false
+ * }
+ * ```
  */
 @JsonClass(generateAdapter = true)
 data class TrmnlDisplayResponse(
-    val status: Int,
+    /**
+     * Status code indicating the result of the request.
+     * - 0: Success
+     * - 500: Error (e.g., device not found)
+     *
+     * Also on `byos_hanami`, the status code is not provided.
+     * See
+     * - https://github.com/usetrmnl/byos_hanami?tab=readme-ov-file#apis
+     * - https://discord.com/channels/1281055965508141100/1331360842809348106/1383221807716237433
+     */
+    val status: Int = HTTP_NONE,
     @Json(name = "image_url") val imageUrl: String?,
     @Json(name = "filename") val imageName: String?,
     @Json(name = "update_firmware") val updateFirmware: Boolean?,