A fork of https://github.com/crosspoint-reader/crosspoint-reader
feat: Prefer ".sleep" over "sleep" for custom image directory (#948)
## Summary
* Custom sleep screen images now load from /.sleep directory
(preferred), falling back to /sleep for backwards compatibility. The
dot-prefix keeps the directory hidden from the file browser.
* Rewrote User Guide section 3.6 to document all six sleep screen modes,
cover settings, and the updated custom image setup.
## Additional Context
* The sleep directoy entry while browsing files was distracting.
---
### AI Usage
While CrossPoint doesn't have restrictions on AI tools in contributing,
please be transparent about their usage as it
helps set the right context for reviewers.
Did you use AI tools to help write this code? _NO_
+37
-9
+22
-5
USER_GUIDE.md
+22
-5
USER_GUIDE.md
···
308
308
309
309
### 3.7 Sleep Screen
310
310
311
-
You can customize the sleep screen by placing custom images in specific locations on the SD card:
311
+
The **Sleep Screen** setting controls what is displayed when the device goes to sleep:
312
+
313
+
| Mode | Behavior |
314
+
|------|----------|
315
+
| **Dark** (default) | The CrossPoint logo on a dark background. |
316
+
| **Light** | The CrossPoint logo on a white background. |
317
+
| **Custom** | A custom image from the SD card (see below). Falls back to **Dark** if no custom image is found. |
318
+
| **Cover** | The cover of the currently open book. Falls back to **Dark** if no book is open. |
319
+
| **Cover + Custom** | The cover of the currently open book. Falls back to **Custom** behavior if no book is open. |
320
+
| **None** | A blank screen. |
321
+
322
+
#### Cover settings
323
+
324
+
When using **Cover** or **Cover + Custom**, two additional settings apply:
325
+
326
+
- **Sleep Screen Cover Mode**: **Fit** (scale to fit, white borders) or **Crop** (scale and crop to fill the screen).
327
+
- **Sleep Screen Cover Filter**: **None** (grayscale), **Contrast** (black & white), or **Inverted** (inverted black & white).
328
+
329
+
#### Custom images
312
330
313
-
- **Single Image:** Place a file named `sleep.bmp` in the root directory.
314
-
- **Multiple Images:** Create a `sleep` directory in the root of the SD card and place any number of `.bmp` images inside. If images are found in this directory, they will take priority over the `sleep.bmp` file, and one will be randomly selected each time the device sleeps.
331
+
To use custom sleep images, set the sleep screen mode to **Custom** or **Cover + Custom**, then place images on the SD card:
315
332
316
-
> [!NOTE]
317
-
> You'll need to set the **Sleep Screen** setting to **Custom** in order to use these images.
333
+
- **Multiple Images (recommended):** Create a `.sleep` directory in the root of the SD card and place any number of `.bmp` images inside. One will be randomly selected each time the device sleeps. (A directory named `sleep` is also accepted as a fallback.)
334
+
- **Single Image:** Place a file named `sleep.bmp` in the root directory. This is used as a fallback if no valid images are found in the `.sleep`/`sleep` directory.
318
335
319
336
> [!TIP]
320
337
> For best results:
+15
-4
src/activities/boot_sleep/SleepActivity.cpp
+15
-4
src/activities/boot_sleep/SleepActivity.cpp
···
32
32
}
33
33
34
34
void SleepActivity::renderCustomSleepScreen() const {
35
-
// Check if we have a /sleep directory
36
-
auto dir = Storage.open("/sleep");
35
+
// Check if we have a /.sleep (preferred) or /sleep directory
36
+
const char* sleepDir = nullptr;
37
+
auto dir = Storage.open("/.sleep");
37
38
if (dir && dir.isDirectory()) {
39
+
sleepDir = "/.sleep";
40
+
} else {
41
+
if (dir) dir.close();
42
+
dir = Storage.open("/sleep");
43
+
if (dir && dir.isDirectory()) {
44
+
sleepDir = "/sleep";
45
+
}
46
+
}
47
+
48
+
if (sleepDir) {
38
49
std::vector<std::string> files;
39
50
char name[500];
40
51
// collect all valid BMP files
···
74
85
}
75
86
APP_STATE.lastSleepImage = randomFileIndex;
76
87
APP_STATE.saveToFile();
77
-
const auto filename = "/sleep/" + files[randomFileIndex];
88
+
const auto filename = std::string(sleepDir) + "/" + files[randomFileIndex];
78
89
FsFile file;
79
90
if (Storage.openFileForRead("SLP", filename, file)) {
80
-
LOG_DBG("SLP", "Randomly loading: /sleep/%s", files[randomFileIndex].c_str());
91
+
LOG_DBG("SLP", "Randomly loading: %s/%s", sleepDir, files[randomFileIndex].c_str());
81
92
delay(100);
82
93
Bitmap bitmap(file, true);
83
94
if (bitmap.parseHeaders() == BmpReaderError::Ok) {