Merge pull request #84 from usetrmnl/76-byos_hanami-compatibility-part-2

[ADDED] Support for BYOS device setup and display image compatibility

Author: hossain-khan

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

@@ -0,0 +1,15 @@
+package ink.trmnl.android.data
+
+/**
+ * Represents the setup information for a TRMNL device.
+ *
+ * This data class is used to encapsulate the result of setting up a new device,
+ * including whether the setup was successful, the device's MAC ID, API key,
+ * and any relevant messages.
+ */
+data class DeviceSetupInfo(
+    val success: Boolean,
+    val deviceMacId: String,
+    val apiKey: String,
+    val message: String,
+)

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

@@ -3,6 +3,7 @@ package ink.trmnl.android.data
 import androidx.annotation.Keep
 import ink.trmnl.android.data.AppConfig.DEFAULT_REFRESH_INTERVAL_SEC
 import ink.trmnl.android.model.TrmnlDeviceType
+import ink.trmnl.android.util.ERROR_TYPE_DEVICE_SETUP_REQUIRED
 import ink.trmnl.android.util.HTTP_200
 import ink.trmnl.android.util.HTTP_500
 import ink.trmnl.android.util.HTTP_OK
@@ -19,7 +20,14 @@ data class TrmnlDisplayInfo constructor(
     val status: Int,
     val trmnlDeviceType: TrmnlDeviceType,
     val imageUrl: String,
-    val imageName: String,
+    /**
+     * The file name of the image to be displayed.
+     *
+     * If this is an error type, it indicates a specific error condition.
+     * For example:
+     * - [ERROR_TYPE_DEVICE_SETUP_REQUIRED]
+     */
+    val imageFileName: String,
     val error: String? = null,
     val refreshIntervalSeconds: Long? = DEFAULT_REFRESH_INTERVAL_SEC,
     /**

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

@@ -2,6 +2,7 @@ package ink.trmnl.android.data
 
 import com.slack.eithernet.ApiResult
 import com.slack.eithernet.InternalEitherNetApi
+import com.slack.eithernet.exceptionOrNull
 import com.squareup.anvil.annotations.optional.SingleIn
 import ink.trmnl.android.BuildConfig.USE_FAKE_API
 import ink.trmnl.android.di.AppScope
@@ -10,6 +11,8 @@ import ink.trmnl.android.model.TrmnlDeviceType
 import ink.trmnl.android.network.TrmnlApiService
 import ink.trmnl.android.network.TrmnlApiService.Companion.CURRENT_PLAYLIST_SCREEN_API_PATH
 import ink.trmnl.android.network.TrmnlApiService.Companion.NEXT_PLAYLIST_SCREEN_API_PATH
+import ink.trmnl.android.network.model.TrmnlDisplayResponse
+import ink.trmnl.android.util.ERROR_TYPE_DEVICE_SETUP_REQUIRED
 import ink.trmnl.android.util.HTTP_200
 import ink.trmnl.android.util.HTTP_500
 import ink.trmnl.android.util.isHttpOk
@@ -57,7 +60,7 @@ class TrmnlDisplayRepository
                         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,
+                        // useBase64 = trmnlDeviceConfig.type == TrmnlDeviceType.BYOS, // Disabled for now
                     )
 
             when (result) {
@@ -66,13 +69,18 @@ class TrmnlDisplayRepository
                 }
                 is ApiResult.Success -> {
                     // Map the response to the display info
-                    val response = result.value
+                    val response: TrmnlDisplayResponse = result.value
+
+                    if (isDeviceSetupRequired(trmnlDeviceConfig, response)) {
+                        return setupRequiredTrmnlDisplayInfo(trmnlDeviceConfig)
+                    }
+
                     val displayInfo =
                         TrmnlDisplayInfo(
                             status = response.status,
                             trmnlDeviceType = trmnlDeviceConfig.type,
                             imageUrl = response.imageUrl ?: "",
-                            imageName = response.imageName ?: "",
+                            imageFileName = response.imageFileName ?: "",
                             error = response.error,
                             refreshIntervalSeconds = response.refreshRate,
                             httpResponseMetadata = extractHttpResponseMetadata(result),
@@ -132,7 +140,7 @@ class TrmnlDisplayRepository
                             status = response.status,
                             trmnlDeviceType = trmnlDeviceConfig.type,
                             imageUrl = response.imageUrl ?: "",
-                            imageName = response.filename ?: "",
+                            imageFileName = response.filename ?: "",
                             error = response.error,
                             refreshIntervalSeconds = response.refreshRateSec,
                             httpResponseMetadata = extractHttpResponseMetadata(result),
@@ -151,6 +159,46 @@ class TrmnlDisplayRepository
             }
         }
 
+        /**
+         * Sets up a new device by calling the setup API endpoint.
+         *
+         * This is only applicable for BYOS devices, as other device types do not require setup.
+         *
+         * @param trmnlDeviceConfig The configuration for the device to be set up.
+         * @return A [DeviceSetupInfo] object containing the result of the setup operation.
+         */
+        suspend fun setupNewDevice(trmnlDeviceConfig: TrmnlDeviceConfig): DeviceSetupInfo {
+            if (trmnlDeviceConfig.type != TrmnlDeviceType.BYOS) {
+                Timber.w("Device setup is only applicable for BYOS devices.")
+            }
+
+            val result =
+                apiService.setupNewDevice(
+                    fullApiUrl = constructApiUrl(trmnlDeviceConfig.apiBaseUrl, TrmnlApiService.SETUP_API_PATH),
+                    deviceMacId = requireNotNull(trmnlDeviceConfig.deviceMacId) { "Device MAC ID is required for setup" },
+                )
+            when (result) {
+                is ApiResult.Failure -> {
+                    Timber.e("Failed to setup device: ${result.exceptionOrNull()}")
+                    return DeviceSetupInfo(
+                        success = false,
+                        deviceMacId = trmnlDeviceConfig.deviceMacId,
+                        apiKey = "",
+                        message = "Failed to setup device with ID (${trmnlDeviceConfig.deviceMacId}). Reason: $result",
+                    )
+                }
+                is ApiResult.Success -> {
+                    Timber.i("Device setup successful: ${result.value}")
+                    return DeviceSetupInfo(
+                        success = true,
+                        deviceMacId = trmnlDeviceConfig.deviceMacId,
+                        apiKey = result.value.apiKey,
+                        message = result.value.message,
+                    )
+                }
+            }
+        }
+
         /**
          * Generates fake display info for debugging purposes without wasting an API request.
          *
@@ -169,7 +217,7 @@ class TrmnlDisplayRepository
                 status = HTTP_200,
                 trmnlDeviceType = TrmnlDeviceType.TRMNL,
                 imageUrl = mockImageUrl,
-                imageName = "mocked-image-" + mockImageUrl.substringAfterLast('?'),
+                imageFileName = "mocked-image-" + mockImageUrl.substringAfterLast('?'),
                 error = null,
                 refreshIntervalSeconds = mockRefreshRate,
             )
@@ -208,7 +256,7 @@ class TrmnlDisplayRepository
                         status = HTTP_500,
                         trmnlDeviceType = trmnlDeviceConfig.type,
                         imageUrl = "",
-                        imageName = "",
+                        imageFileName = "",
                         error = "API failure",
                         refreshIntervalSeconds = 0L,
                     )
@@ -222,7 +270,7 @@ class TrmnlDisplayRepository
                         status = HTTP_500,
                         trmnlDeviceType = trmnlDeviceConfig.type,
                         imageUrl = "",
-                        imageName = "",
+                        imageFileName = "",
                         error = "HTTP failure: ${failure.code}, error: ${failure.error}",
                         refreshIntervalSeconds = 0L,
                     )
@@ -236,7 +284,7 @@ class TrmnlDisplayRepository
                         status = HTTP_500,
                         trmnlDeviceType = trmnlDeviceConfig.type,
                         imageUrl = "",
-                        imageName = "",
+                        imageFileName = "",
                         error = "Network failure: ${failure.error.localizedMessage}",
                         refreshIntervalSeconds = 0L,
                     )
@@ -250,7 +298,7 @@ class TrmnlDisplayRepository
                         status = HTTP_500,
                         trmnlDeviceType = trmnlDeviceConfig.type,
                         imageUrl = "",
-                        imageName = "",
+                        imageFileName = "",
                         error = "Unknown failure: ${failure.error.localizedMessage}",
                         refreshIntervalSeconds = 0L,
                     )
@@ -285,4 +333,38 @@ class TrmnlDisplayRepository
                 timestamp = System.currentTimeMillis(),
             )
         }
+
+        /**
+         * Right now there is no good known way to determine if a device requires setup.
+         * The logic here is based on sample responses from the Terminus server API.
+         *
+         * See
+         * - https://discord.com/channels/1281055965508141100/1331360842809348106/1384605617456545904
+         * - https://discord.com/channels/1281055965508141100/1384605617456545904/1384613229086511135
+         */
+        private fun isDeviceSetupRequired(
+            trmnlDeviceConfig: TrmnlDeviceConfig,
+            response: TrmnlDisplayResponse,
+        ): Boolean =
+            trmnlDeviceConfig.type == TrmnlDeviceType.BYOS &&
+                response.imageFileName?.startsWith("setup", ignoreCase = true) == true &&
+                // This ensures that no screen is generated yet for the device
+                response.imageUrl?.contains("screens", ignoreCase = true) == false
+
+        /**
+         * Creates a [TrmnlDisplayInfo] indicating that the device requires setup.
+         *
+         * This is used when the device is not yet configured and needs to be set up before it can display content.
+         * @see ERROR_TYPE_DEVICE_SETUP_REQUIRED
+         * @see [isDeviceSetupRequired]
+         */
+        private fun setupRequiredTrmnlDisplayInfo(trmnlDeviceConfig: TrmnlDeviceConfig): TrmnlDisplayInfo =
+            TrmnlDisplayInfo(
+                status = HTTP_500,
+                trmnlDeviceType = trmnlDeviceConfig.type,
+                imageUrl = "",
+                imageFileName = ERROR_TYPE_DEVICE_SETUP_REQUIRED,
+                error = "Device setup required",
+                refreshIntervalSeconds = 0L,
+            )
     }

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

@@ -0,0 +1,31 @@
+package ink.trmnl.android.model
+
+import com.squareup.moshi.Json
+import com.squareup.moshi.JsonClass
+
+/**
+ * Data class representing the response from the TRMNL setup API.
+ *
+ * Sample JSON response:
+ * ```json
+ * {
+ *     "api_key": "abc1234567890abcdef",
+ *     "friendly_id": "GO87665",
+ *     "image_url": "https://localhost:1234/assets/setup.bmp",
+ *     "message": "Welcome to Terminus!"
+ * }
+ * ```
+ *
+ * @property apiKey The API key for the device.
+ * @property friendlyId A user-friendly identifier for the device.
+ * @property imageUrl The URL of an image to display during setup.
+ * @property message A welcome message or setup instructions.
+ * @see ink.trmnl.android.network.TrmnlApiService.setupNewDevice
+ */
+@JsonClass(generateAdapter = true)
+data class TrmnlSetupResponse(
+    @Json(name = "api_key") val apiKey: String,
+    @Json(name = "friendly_id") val friendlyId: String,
+    @Json(name = "image_url") val imageUrl: String,
+    @Json(name = "message") val message: String,
+)

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

@@ -2,14 +2,15 @@ package ink.trmnl.android.network
 
 import com.slack.eithernet.ApiResult
 import ink.trmnl.android.data.TrmnlDisplayRepository
+import ink.trmnl.android.model.TrmnlSetupResponse
 import ink.trmnl.android.network.model.TrmnlCurrentImageResponse
 import ink.trmnl.android.network.model.TrmnlDisplayResponse
 import retrofit2.http.GET
 import retrofit2.http.Header
 import retrofit2.http.Url
 
 /**
- * API service interface for TRMNL.
+ * API service interface for TRMNL or BYOS servers.
  *
  * This interface defines the endpoints for the TRMNL API.
  *
@@ -22,18 +23,39 @@ import retrofit2.http.Url
 interface TrmnlApiService {
     companion object {
         /**
-         * https://docs.usetrmnl.com/go/private-api/fetch-screen-content#auto-advance-content
+         * Path for the TRMNL API endpoint that provides the next image in a playlist.
+         *
+         * - https://docs.usetrmnl.com/go/private-api/fetch-screen-content#auto-advance-content
+         * - https://github.com/usetrmnl/byos_hanami?tab=readme-ov-file#display
          *
          * @see getNextDisplayData
          */
         internal const val NEXT_PLAYLIST_SCREEN_API_PATH = "api/display"
 
         /**
+         * Path for the TRMNL API endpoint that provides the current image in a playlist.
+         *
          * https://docs.usetrmnl.com/go/private-api/fetch-screen-content#current-screen
          *
          * @see getCurrentDisplayData
          */
         internal const val CURRENT_PLAYLIST_SCREEN_API_PATH = "api/current_screen"
+
+        /**
+         * Path for the TRMNL API endpoint used for new device setup.
+         *
+         * https://github.com/usetrmnl/byos_hanami?tab=readme-ov-file#setup-1
+         *
+         * @see setupNewDevice
+         */
+        internal const val SETUP_API_PATH = "api/setup/"
+
+        /**
+         * Default content type for API requests.
+         *
+         * This is used when setting up a new device or making other API calls that require a content type header.
+         */
+        private const val DEFAULT_CONTENT_TYPE = "application/json"
     }
 
     /**
@@ -68,4 +90,21 @@ interface TrmnlApiService {
         @Url fullApiUrl: String,
         @Header("access-token") accessToken: String,
     ): ApiResult<TrmnlCurrentImageResponse, Unit>
+
+    /**
+     * Setup a new TRMNL device using it's MAC ID. Using same API with same ID has no effect.
+     *
+     * This API is typically used once during the initial setup of a BYOS device.
+     * See https://github.com/usetrmnl/byos_hanami?tab=readme-ov-file#setup-1
+     *
+     * @param fullApiUrl The complete API URL to call (e.g., "https://your-server.com/api/setup").
+     * @param deviceMacId The device's MAC address, sent in the "ID" header.
+     * @return An [ApiResult] containing [TrmnlSetupResponse] on success.
+     */
+    @GET
+    suspend fun setupNewDevice(
+        @Url fullApiUrl: String,
+        @Header("ID") deviceMacId: String,
+        @Header("Content-Type") contentType: String = DEFAULT_CONTENT_TYPE,
+    ): ApiResult<TrmnlSetupResponse, Unit>
 }

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

@@ -49,6 +49,17 @@ import ink.trmnl.android.util.HTTP_NONE
  *   "update_firmware": false
  * }
  * ```
+ *
+ * Sample 4404 response from BYOS Hanami server:
+ * ```json
+ * {
+ *   "type": "/problem_details#device_id",
+ *   "title": "Not Found",
+ *   "status": 404,
+ *   "detail": "Invalid device ID.",
+ *   "instance": "/api/display"
+ * }
+ * ```
  */
 @JsonClass(generateAdapter = true)
 data class TrmnlDisplayResponse(
@@ -64,7 +75,7 @@ data class TrmnlDisplayResponse(
      */
     val status: Int = HTTP_NONE,
     @Json(name = "image_url") val imageUrl: String?,
-    @Json(name = "filename") val imageName: String?,
+    @Json(name = "filename") val imageFileName: String?,
     @Json(name = "update_firmware") val updateFirmware: Boolean?,
     @Json(name = "firmware_url") val firmwareUrl: String?,
     @Json(name = "refresh_rate") val refreshRate: Long?,