Add doc about external resources.
This commit is contained in:
parent
8f5df5385c
commit
60abbf0639
|
@ -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)
|
- [Generate the fonts and symbols](src/displayapp/fonts/README.md)
|
||||||
- [Tips on designing an app UI](doc/ui_guidelines.md)
|
- [Tips on designing an app UI](doc/ui_guidelines.md)
|
||||||
- [Bootloader, OTA and DFU](bootloader/README.md)
|
- [Bootloader, OTA and DFU](bootloader/README.md)
|
||||||
|
- [External resources](doc/ExternalResources.md)
|
||||||
- [Versioning](doc/versioning.md)
|
- [Versioning](doc/versioning.md)
|
||||||
- [Project branches](doc/branches.md)
|
- [Project branches](doc/branches.md)
|
||||||
- [Files included in the release notes](doc/filesInReleaseNotes.md)
|
- [Files included in the release notes](doc/filesInReleaseNotes.md)
|
||||||
|
|
70
doc/ExternalResources.md
Normal file
70
doc/ExternalResources.md
Normal 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);
|
||||||
|
}
|
||||||
|
|
||||||
|
```
|
||||||
|
|
BIN
doc/gettingStarted/itd-external-resources.png
Normal file
BIN
doc/gettingStarted/itd-external-resources.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 12 KiB |
|
@ -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
|
- Open settings by tapping the cogwheel on the bottom right
|
||||||
- Swipe up until you find an entry named **Firmware** and tap on it
|
- 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
|
- 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)
|
||||||
|
|
Loading…
Reference in New Issue
Block a user