Author: Jean-François Milants <jf@codingfield.com>
Add doc about external resources.
README.md | 1 doc/ExternalResources.md | 70 +++++++++++++++++++++++++++ doc/gettingStarted/updating-software.md | 32 ++++++++++++
diff --git a/README.md b/README.md index a3d2229bbeed0c3d629fe2a38c20acbe72677bf4..6fd4158600000642a6bb4bfcc74f8a4f1360a06a 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,7 @@ - [How to implement an application](doc/code/Apps.md) - [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) diff --git a/doc/ExternalResources.md b/doc/ExternalResources.md new file mode 100644 index 0000000000000000000000000000000000000000..85319f6fc9e1dd2d6c4f5c5cc0750f5ef4961877 --- /dev/null +++ b/doc/ExternalResources.md @@ -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); +} + +``` + diff --git a/doc/gettingStarted/itd-external-resources.png b/doc/gettingStarted/itd-external-resources.png new file mode 100644 index 0000000000000000000000000000000000000000..b3ff99be20c0c051c8c677225cc0edc6ebf87a97 Binary files /dev/null and b/doc/gettingStarted/itd-external-resources.png differ diff --git a/doc/gettingStarted/updating-software.md b/doc/gettingStarted/updating-software.md index d302607e295f48cf6be32d96ca09626bf5de20f2..5c867023dc6b1275e0bfb7bf4aa6cb3a1e0dcf98 100644 --- a/doc/gettingStarted/updating-software.md +++ b/doc/gettingStarted/updating-software.md @@ -39,3 +39,35 @@ - From the watchface, swipe **right** to display the *quick settings menu* - 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. + + + +Amazfish automatically detects the file type (firmware or resources) and apply the corresponding flash procedure when you hit the button **Send file**. + + + +## ITD + +Run `itctl` with the `res` command: + +``` +itctl res load infinitime-resources-1.10.0.zip +``` + +Example: + +