Add Gift Mode feature for BYOD gifting

- New GiftModeSettingsActivity for configuring gift mode (names, device code)
- Gift mode display shows setup instructions for recipient
- Gift screensaver uses generic_display with 'tap home button' hint
- Auto-disable gift mode when credentials are saved
- Add Developer Perks hint to Settings and Credentials pages
- Settings UI improvements: grey button style, single-column layout
- Make NOOK_IP configurable via environment variable

Author: bpmct

AGENTS/build-tooling.md

@@ -76,3 +76,21 @@ When working in a git worktree, you need:
 ## Release flow
 
 Release guidance now lives in `AGENTS/release.md`.
+
+## Image Generation with ImageMagick
+
+For generating static images (e.g., screensavers), use ImageMagick `convert`:
+
+```bash
+# Example: Add text to existing image and rotate for NOOK screensaver
+convert res/drawable-mdpi/generic_display.jpg \
+  -gravity South -pointsize 16 -fill 'gray50' -font DejaVu-Sans \
+  -annotate +0+30 "Your text here" \
+  -rotate 90 \
+  res/drawable-mdpi/output.png
+```
+
+Key notes:
+- Use `-font DejaVu-Sans` to avoid italic text (default can be italic)
+- NOOK screensaver is native portrait (600x800), so rotate landscape images 90° CW
+- Use `gray50` for subtle text matching app UI

AndroidManifest.xml

@@ -40,6 +40,11 @@
             android:configChanges="orientation|keyboardHidden|screenSize"
             android:label="Credentials"
             android:theme="@style/FullscreenTheme" />
+        <activity
+            android:name=".GiftModeSettingsActivity"
+            android:configChanges="orientation|keyboardHidden|screenSize"
+            android:label="Gift Mode Settings"
+            android:theme="@style/FullscreenTheme" />
     </application>
 
 </manifest>

res/drawable-mdpi/gift_screensaver.png

@@ -11,6 +11,10 @@ public class ApiPrefs {
     private static final String DEFAULT_API_BASE_URL = "https://usetrmnl.com/api";
     private static final String KEY_ALLOW_SLEEP = "allow_sleep";
     private static final String KEY_FILE_LOGGING = "file_logging";
+    private static final String KEY_GIFT_MODE = "gift_mode";
+    private static final String KEY_FRIENDLY_DEVICE_CODE = "friendly_device_code";
+    private static final String KEY_GIFT_FROM_NAME = "gift_from_name";
+    private static final String KEY_GIFT_TO_NAME = "gift_to_name";
     private static final String SCREENSAVER_PATH = "/media/screensavers/TRMNL/display.png";
 
     public static boolean hasCredentials(Context context) {
@@ -91,7 +95,7 @@ private static String normalizeBaseUrl(String baseUrl, String defaultBaseUrl) {
     /** Whether the device may sleep between display updates (Electric-Sign-style). Default true. */
     public static boolean isAllowSleep(Context context) {
         SharedPreferences prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE);
-        return prefs.getBoolean(KEY_ALLOW_SLEEP, true);
+        return prefs.getBoolean(KEY_ALLOW_SLEEP, false);
     }
 
     public static void setAllowSleep(Context context, boolean allow) {
@@ -113,4 +117,50 @@ public static void setFileLoggingEnabled(Context context, boolean enabled) {
     public static String getScreensaverPath() {
         return SCREENSAVER_PATH;
     }
+
+    public static boolean isGiftModeEnabled(Context context) {
+        SharedPreferences prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE);
+        return prefs.getBoolean(KEY_GIFT_MODE, false);
+    }
+
+    public static void setGiftModeEnabled(Context context, boolean enabled) {
+        context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE).edit()
+                .putBoolean(KEY_GIFT_MODE, enabled).commit();
+    }
+
+    public static String getFriendlyDeviceCode(Context context) {
+        SharedPreferences prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE);
+        String value = prefs.getString(KEY_FRIENDLY_DEVICE_CODE, null);
+        if (value == null || value.trim().length() == 0) return null;
+        return value.trim();
+    }
+
+    public static void saveFriendlyDeviceCode(Context context, String code) {
+        context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE).edit()
+                .putString(KEY_FRIENDLY_DEVICE_CODE, code != null ? code.trim() : "").commit();
+    }
+
+    public static String getGiftFromName(Context context) {
+        SharedPreferences prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE);
+        String value = prefs.getString(KEY_GIFT_FROM_NAME, null);
+        if (value == null || value.trim().length() == 0) return null;
+        return value.trim();
+    }
+
+    public static void saveGiftFromName(Context context, String name) {
+        context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE).edit()
+                .putString(KEY_GIFT_FROM_NAME, name != null ? name.trim() : "").commit();
+    }
+
+    public static String getGiftToName(Context context) {
+        SharedPreferences prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE);
+        String value = prefs.getString(KEY_GIFT_TO_NAME, null);
+        if (value == null || value.trim().length() == 0) return null;
+        return value.trim();
+    }
+
+    public static void saveGiftToName(Context context, String name) {
+        context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE).edit()
+                .putString(KEY_GIFT_TO_NAME, name != null ? name.trim() : "").commit();
+    }
 }

src/com/bpmct/trmnl_nook_simple_touch/ApiPrefs.java

@@ -59,6 +59,19 @@ protected void onCreate(Bundle savedInstanceState) {
                 ViewGroup.LayoutParams.WRAP_CONTENT);
         inner.addView(baseUrlInput, baseUrlParams);
 
+        // Show hint about where to find credentials if using default URL
+        String currentBaseUrl = ApiPrefs.getApiBaseUrl(this);
+        if (currentBaseUrl != null && currentBaseUrl.contains("usetrmnl.com")) {
+            TextView credHint = new TextView(this);
+            credHint.setText("Find credentials in Device Settings → Developer Perks on trmnl.com");
+            credHint.setTextSize(11);
+            credHint.setTextColor(0xFF888888);
+            LinearLayout.LayoutParams hintParams = new LinearLayout.LayoutParams(
+                    ViewGroup.LayoutParams.WRAP_CONTENT, ViewGroup.LayoutParams.WRAP_CONTENT);
+            hintParams.topMargin = 8;
+            inner.addView(credHint, hintParams);
+        }
+
         TextView idLabel = new TextView(this);
         idLabel.setText("Device ID (MAC Address)");
         idLabel.setTextSize(14);
@@ -156,6 +169,8 @@ public void onClick(View v) {
                 }
                 ApiPrefs.saveCredentials(CredentialsActivity.this, id, token);
                 ApiPrefs.saveApiBaseUrl(CredentialsActivity.this, baseUrl);
+                // Auto-disable gift mode when credentials are saved
+                ApiPrefs.setGiftModeEnabled(CredentialsActivity.this, false);
                 statusView.setText("Saved.");
                 android.content.Intent intent = new android.content.Intent(CredentialsActivity.this, DisplayActivity.class);
                 intent.putExtra(DisplayActivity.EXTRA_CLEAR_IMAGE, true);

src/com/bpmct/trmnl_nook_simple_touch/CredentialsActivity.java

@@ -369,7 +369,9 @@ protected void onResume() {
         boolean wifiJustOn = ensureWifiOnWhenForeground();
 
         applyIntentState(getIntent());
-        if (USE_GENERIC_IMAGE) {
+        if (ApiPrefs.isGiftModeEnabled(this)) {
+            showGiftModeScreen();
+        } else if (USE_GENERIC_IMAGE) {
             showGenericImageAndSleep();
         } else if (ensureCredentials()) {
             if (!fetchInProgress) {
@@ -858,6 +860,155 @@ private void setBootStatus(String status) {
         }
     }
 
+    private void showGiftModeScreen() {
+        hideBootScreen();
+        if (bootLayout != null) bootLayout.setVisibility(View.GONE);
+        if (logView != null) logView.setVisibility(View.GONE);
+        if (imageRotateLayout != null) imageRotateLayout.setVisibility(View.GONE);
+        if (contentScroll != null) contentScroll.setVisibility(View.VISIBLE);
+        
+        String code = ApiPrefs.getFriendlyDeviceCode(this);
+        String fromName = ApiPrefs.getGiftFromName(this);
+        String toName = ApiPrefs.getGiftToName(this);
+        
+        // Build a left-aligned layout
+        ScrollView.LayoutParams scrollParams = new ScrollView.LayoutParams(
+                ViewGroup.LayoutParams.FILL_PARENT, ViewGroup.LayoutParams.FILL_PARENT);
+        
+        LinearLayout giftLayout = new LinearLayout(this);
+        giftLayout.setOrientation(LinearLayout.VERTICAL);
+        giftLayout.setGravity(Gravity.CENTER_VERTICAL);
+        giftLayout.setPadding(50, 40, 50, 40);
+        giftLayout.setLayoutParams(scrollParams);
+        
+        // Logo + Title row
+        LinearLayout headerRow = new LinearLayout(this);
+        headerRow.setOrientation(LinearLayout.HORIZONTAL);
+        headerRow.setGravity(Gravity.CENTER_VERTICAL);
+        
+        ImageView logo = new ImageView(this);
+        logo.setImageResource(R.drawable.ic_launcher);
+        headerRow.addView(logo);
+        
+        TextView title = new TextView(this);
+        title.setText("TRMNL");
+        title.setTextSize(22);
+        title.setTextColor(0xFF000000);
+        title.setPadding(12, 0, 0, 0);
+        headerRow.addView(title);
+        
+        giftLayout.addView(headerRow);
+        
+        // Greeting
+        StringBuilder greeting = new StringBuilder();
+        if (toName != null && toName.length() > 0) {
+            greeting.append("Hey ").append(toName).append("! ");
+        }
+        if (fromName != null && fromName.length() > 0) {
+            greeting.append(fromName).append(" gifted you this display!");
+        } else {
+            greeting.append("This display was gifted to you!");
+        }
+        
+        TextView greetingView = new TextView(this);
+        greetingView.setText(greeting.toString());
+        greetingView.setTextSize(14);
+        greetingView.setTextColor(0xFF000000);
+        LinearLayout.LayoutParams greetParams = new LinearLayout.LayoutParams(
+                ViewGroup.LayoutParams.FILL_PARENT, ViewGroup.LayoutParams.WRAP_CONTENT);
+        greetParams.topMargin = 16;
+        giftLayout.addView(greetingView, greetParams);
+        
+        // Description
+        TextView desc = new TextView(this);
+        desc.setText("Use it for weather, calendars, news, or hundreds of other plugins from trmnl.com");
+        desc.setTextSize(12);
+        desc.setTextColor(0xFF666666);
+        LinearLayout.LayoutParams descParams = new LinearLayout.LayoutParams(
+                ViewGroup.LayoutParams.FILL_PARENT, ViewGroup.LayoutParams.WRAP_CONTENT);
+        descParams.topMargin = 6;
+        giftLayout.addView(desc, descParams);
+        
+        // Divider line
+        View divider = new View(this);
+        divider.setBackgroundColor(0xFFCCCCCC);
+        LinearLayout.LayoutParams divParams = new LinearLayout.LayoutParams(
+                ViewGroup.LayoutParams.FILL_PARENT, 1);
+        divParams.topMargin = 20;
+        giftLayout.addView(divider, divParams);
+        
+        // Setup steps title
+        TextView stepsTitle = new TextView(this);
+        stepsTitle.setText("SETUP");
+        stepsTitle.setTextSize(11);
+        stepsTitle.setTextColor(0xFF888888);
+        LinearLayout.LayoutParams stepsTitleParams = new LinearLayout.LayoutParams(
+                ViewGroup.LayoutParams.FILL_PARENT, ViewGroup.LayoutParams.WRAP_CONTENT);
+        stepsTitleParams.topMargin = 16;
+        giftLayout.addView(stepsTitle, stepsTitleParams);
+        
+        // Step 1
+        giftLayout.addView(createStepRow("1", "Sign up at trmnl.com/signup"), createStepParams(12));
+        
+        // Step 2
+        String step2Text = (code != null && code.length() > 0) 
+                ? "Add device with code: " + code 
+                : "Add device (get code from gifter)";
+        giftLayout.addView(createStepRow("2", step2Text), createStepParams(8));
+        
+        // Step 3
+        giftLayout.addView(createStepRow("3", "Tap screen → Settings → Edit"), createStepParams(8));
+        
+        // Replace contentView's parent contents
+        if (contentScroll != null) {
+            contentScroll.removeAllViews();
+            contentScroll.setFillViewport(true);
+            contentScroll.addView(giftLayout);
+        }
+        
+        // Write gift mode screen to screensaver so NOOK shows it when asleep
+        writeGiftModeScreensaver(code, fromName, toName);
+    }
+    
+    private LinearLayout createStepRow(String number, String text) {
+        LinearLayout row = new LinearLayout(this);
+        row.setOrientation(LinearLayout.HORIZONTAL);
+        
+        TextView numView = new TextView(this);
+        numView.setText(number);
+        numView.setTextSize(16);
+        numView.setTextColor(0xFF000000);
+        numView.setGravity(Gravity.CENTER);
+        numView.setBackgroundColor(0xFFEEEEEE);
+        numView.setPadding(12, 4, 12, 4);
+        row.addView(numView);
+        
+        TextView textView = new TextView(this);
+        textView.setText(text);
+        textView.setTextSize(12);
+        textView.setTextColor(0xFF000000);
+        textView.setPadding(12, 0, 0, 0);
+        textView.setGravity(Gravity.CENTER_VERTICAL);
+        row.addView(textView);
+        
+        return row;
+    }
+    
+    private LinearLayout.LayoutParams createStepParams(int topMargin) {
+        LinearLayout.LayoutParams params = new LinearLayout.LayoutParams(
+                ViewGroup.LayoutParams.FILL_PARENT, ViewGroup.LayoutParams.WRAP_CONTENT);
+        params.topMargin = topMargin;
+        return params;
+    }
+    
+    private void writeGiftModeScreensaver(String code, String fromName, String toName) {
+        // Use gift screensaver image (already in native portrait orientation 600x800)
+        Bitmap bitmap = BitmapFactory.decodeResource(getResources(), R.drawable.gift_screensaver);
+        if (bitmap != null) {
+            writeScreenshotToScreensaver(bitmap);
+        }
+    }
+
     private void toggleMenu() {
         if (menuVisible) {
             hideMenu();
@@ -1011,6 +1162,10 @@ public void run() {
     }
 
     private boolean ensureCredentials() {
+        // Don't redirect to settings if gift mode is enabled
+        if (ApiPrefs.isGiftModeEnabled(this)) {
+            return false;
+        }
         if (!ApiPrefs.hasCredentials(this)) {
             startActivity(new Intent(this, SettingsActivity.class));
             return false;