Add doc about external resources.

This commit is contained in:
Jean-François Milants 2022-10-02 12:27:10 +02:00
parent 8f5df5385c
commit 60abbf0639
4 changed files with 103 additions and 0 deletions

View file

@ -28,6 +28,7 @@ Fast open-source firmware for the [PineTime smartwatch](https://www.pine64.org/p
- [Generate the fonts and symbols](src/displayapp/fonts/README.md)
- [Tips on designing an app UI](doc/ui_guidelines.md)
- [Bootloader, OTA and DFU](bootloader/README.md)
- [External resources](doc/ExternalResources.md)
- [Versioning](doc/versioning.md)
- [Project branches](doc/branches.md)
- [Files included in the release notes](doc/filesInReleaseNotes.md)

70
doc/ExternalResources.md Normal file
View file

@ -0,0 +1,70 @@
# External resources
Since InfiniTime 1.11 apps and watchfaces can benefit from the external flash memory to store images and fonts.
This external memory is a lot bigger (4MB) than the internal memory that contains the firmware (512KB).
This page describes how the resources are integrated in InfiniTime from a developer perspective. [This page](gettingStarted/updating-software.md) explains how to install and update the external resources using companion apps.
## Resources generation
Resources are generated at build time via the [CMake target `Generate Resources`](https://github.com/InfiniTimeOrg/InfiniTime/blob/develop/src/resources/CMakeLists.txt#L19).
It runs 3 Python scripts that respectively convert the fonts to binary format, convert the images to binary format and package everything in a .zip file.
The resulting file `infinitime-resources-x.y.z.zip` contains the images and fonts converted in binary `.bin` files and a JSON file `resources.json`.
Companion apps use this file to upload the files to the watch.
```
{
"resources": [
{
"filename": "lv_font_dots_40.bin",
"path": "/fonts/lv_font_dots_40.bin"
}
],
"obsolete_files": [
{
"path": "/example-of-obsolete-file.bin",
"since": "1.11.0"
}
]
}
```
The resource JSON file describes an array of resources and an array of obsolete files :
- `resources` : a resource is a file that must be flashed to the watch
- `filename`: name of the resources in the zip file.
- `path` : file path and name where the file must be flashed in the watch FS.
- `obsolete_files` : files that are not needed anymore in the memory of the watch that can be deleted during the update procedure.
- `path` : path of the file in the watch FS
- `since` : version of InfiniTime that made this file obsolete.
## Resources update procedure
The update procedure is based on the [BLE FS API](BLEFS.md). The companion app simply write the binary files to the watch FS using information from the file `resources.json`.
## Working with external resources in the code
Load a picture from the external resources:
```
lv_obj_t* logo = lv_img_create(lv_scr_act(), nullptr);
lv_img_set_src(logo, "F:/images/logo.bin");
```
Load a font from the external resources: you first need to check that the file actually exists. LVGL will crash when trying to open a font that doesn't exist.
```
lv_font_t* font_teko = nullptr;
if (filesystem.FileOpen(&f, "/fonts/font.bin", LFS_O_RDONLY) >= 0) {
filesystem.FileClose(&f);
font_teko = lv_font_load("F:/fonts/font.bin");
}
if(font != nullptr) {
lv_obj_set_style_local_text_font(label, LV_LABEL_PART_MAIN, LV_STATE_DEFAULT, font);
}
```

Binary file not shown.

After

Width:  |  Height:  |  Size: 12 KiB

View file

@ -39,3 +39,35 @@ You can validate your updated firmware on InfiniTime >= 1.0 by following this si
- Open settings by tapping the cogwheel on the bottom right
- Swipe up until you find an entry named **Firmware** and tap on it
- If the firmware is not validated yet, you can either validate the running firmware, or reset and revert to the previous firmware version
# Updating resources
Since InfiniTime 1.11 apps and watchfaces can take benefit of the external flash memory to store their pictures and fonts.
This external memory is a lot bigger (4MB) than the internal memory where the firmware is flashed (512KB).
Since those resources are not part of the firmware, they need to be flashed and updated separately.
Resources are packaged into a single .zip file named `infinitime-resources-x.y.z.zip` (where `x`, `y` and `z` are the version numbers of InfiniTime).
You can use the companion app of your choice to flash the resources.
**Note : at the time of writing this page, [Amazfish](https://github.com/piggz/harbour-amazfish) and [ITD](https://gitea.arsenm.dev/Arsen6331/itd) have already integrated this functionality. Other companion apps will hopefully implement it soon!*
## Amazfish
Use the `Download file` functionality of Amazfish.
![Update resources with Amazfish - Download file](amazfish-external-resources-1.png)
Amazfish automatically detects the file type (firmware or resources) and apply the corresponding flash procedure when you hit the button **Send file**.
![Update resources with Amazfish](amazfish-external-resources-2.png)
## ITD
Run `itctl` with the `res` command:
```
itctl res load infinitime-resources-1.10.0.zip
```
Example:
![Update resources using itctl](itd-external-resources.png)