diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ExternalResources.md | 70 | ||||
| -rw-r--r-- | doc/buildAndProgram.md | 41 | ||||
| -rw-r--r-- | doc/code/Apps.md | 2 | ||||
| -rw-r--r-- | doc/gettingStarted/itd-external-resources.png | bin | 0 -> 11869 bytes | |||
| -rw-r--r-- | doc/gettingStarted/updating-software.md | 32 |
5 files changed, 106 insertions, 39 deletions
diff --git a/doc/ExternalResources.md b/doc/ExternalResources.md new file mode 100644 index 00000000..85319f6f --- /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/buildAndProgram.md b/doc/buildAndProgram.md index 58d0f72e..78bea1b4 100644 --- a/doc/buildAndProgram.md +++ b/doc/buildAndProgram.md @@ -40,12 +40,9 @@ CMake configures the project according to variables you specify the command line ----------|-------------|--------| **ARM_NONE_EABI_TOOLCHAIN_PATH**|path to the toolchain directory|`-DARM_NONE_EABI_TOOLCHAIN_PATH=/home/jf/nrf52/gcc-arm-none-eabi-10.3-2021.10/`| **NRF5_SDK_PATH**|path to the NRF52 SDK|`-DNRF5_SDK_PATH=/home/jf/nrf52/Pinetime/sdk`| -**USE_JLINK, USE_GDB_CLIENT and USE_OPENOCD**|Enable *JLink* mode, *GDB Client* (Black Magic Probe) mode or *OpenOCD* mode (set the one you want to use to `1`)|`-DUSE_JLINK=1` **CMAKE_BUILD_TYPE (\*)**| Build type (Release or Debug). Release is applied by default if this variable is not specified.|`-DCMAKE_BUILD_TYPE=Debug` -**NRFJPROG**|Path to the NRFJProg executable. Used only if `USE_JLINK` is 1.|`-DNRFJPROG=/opt/nrfjprog/nrfjprog` -**GDB_CLIENT_BIN_PATH**|Path to arm-none-eabi-gdb executable. Used only if `USE_GDB_CLIENT` is 1.|`-DGDB_CLIENT_BIN_PATH=/home/jf/nrf52/gcc-arm-none-eabi-9-2019-q4-major/bin/arm-none-eabi-gdb` -**GDB_CLIENT_TARGET_REMOTE**|Target remote connection string. Used only if `USE_GDB_CLIENT` is 1.|`-DGDB_CLIENT_TARGET_REMOTE=/dev/ttyACM0` **BUILD_DFU (\*\*)**|Build DFU files while building (needs [adafruit-nrfutil](https://github.com/adafruit/Adafruit_nRF52_nrfutil)).|`-DBUILD_DFU=1` +**BUILD_RESOURCES (\*\*)**| Generate external resource while building (needs [lv_font_conv](https://github.com/lvgl/lv_font_conv) and [lv_img_conv](https://github.com/lvgl/lv_img_conv). |`-DBUILD_RESOURCES=1` **TARGET_DEVICE**|Target device, used for hardware configuration. Allowed: `PINETIME, MOY-TFK5, MOY-TIN5, MOY-TON5, MOY-UNK`|`-DTARGET_DEVICE=PINETIME` (Default) #### (\*) Note about **CMAKE_BUILD_TYPE** @@ -56,30 +53,16 @@ The *Debug* mode disables all optimizations, which makes the code easier to debu #### (\*\*) Note about **BUILD_DFU** DFU files are the files you'll need to install your build of InfiniTime using OTA (over-the-air) mechanism. To generate the DFU file, the Python tool [adafruit-nrfutil](https://github.com/adafruit/Adafruit_nRF52_nrfutil) is needed on your system. Check that this tool is properly installed before enabling this option. -#### CMake command line for JLink +#### CMake command ``` -cmake -DARM_NONE_EABI_TOOLCHAIN_PATH=... -DNRF5_SDK_PATH=... -DUSE_JLINK=1 -DNRFJPROG=... ../ -``` - -#### CMake command line for GDB Client (Black Magic Probe) - -``` -cmake -DARM_NONE_EABI_TOOLCHAIN_PATH=... -DNRF5_SDK_PATH=... -DUSE_GDB_CLIENT=1 -DGDB_CLIENT_BIN_PATH=... -DGDB_CLIENT_TARGET_REMOTE=... ../ -``` - -#### CMake command line for OpenOCD - -``` -cmake -DARM_NONE_EABI_TOOLCHAIN_PATH=... -DNRF5_SDK_PATH=... -DUSE_OPENOCD=1 -DGDB_CLIENT_BIN_PATH=[optional] ../ +cmake -DARM_NONE_EABI_TOOLCHAIN_PATH=... -DNRF5_SDK_PATH=... ``` ### Build the project During the project generation, CMake created the following targets: -- **FLASH_ERASE** : mass erase the flash memory of the NRF52. -- **FLASH_pinetime-app** : flash the firmware into the NRF52. - **pinetime-app** : build the standalone (without bootloader support) version of the firmware. - **pinetime-recovery** : build the standalone recovery version of infinitime (light firmware that only supports OTA and basic UI) - **pinetime-recovery-loader** : build the standalone tool that flashes the recovery firmware into the external SPI flash @@ -107,24 +90,6 @@ Binary files are generated into the folder `src`: The same files are generated for **pinetime-recovery** and **pinetime-recoveryloader** -### Program and run - -#### Using CMake targets - -These target have been configured during the project generation by CMake according to the parameters you provided to the command line. - -Mass erase: - -``` -make FLASH_ERASE -``` - -Flash the application: - -``` -make FLASH_pinetime-app -``` - ### How to generate files needed by the factory These files are needed by the Pine64 factory to flash InfiniTime as the default firmware on the PineTimes. diff --git a/doc/code/Apps.md b/doc/code/Apps.md index c756a8b4..ad0f0403 100644 --- a/doc/code/Apps.md +++ b/doc/code/Apps.md @@ -99,7 +99,7 @@ Now, go to the function `DisplayApp::LoadApp` and add another case to the switch The case will be the id you gave your app earlier. If your app needs any additional arguments, this is the place to pass them. -If you want to add your app in the app launcher, add your app in [displayapp/screens/ApplicationList.cpp](/src/displayapp/screens/ApplicationList.cpp) to one of the `CreateScreen` functions, or add another `CreateScreen` function if there are no empty spaces for your app. If your app is a setting, do the same procedure in [displayapp/screens/settings/Settings.cpp](/src/displayapp/screens/settings/Settings.cpp). +If you want to add your app in the app launcher, add your app in [displayapp/screens/ApplicationList.h](/src/displayapp/screens/ApplicationList.h) to the array containing the applications and their corresponding symbol. If your app is a setting, do the same procedure in [displayapp/screens/settings/Settings.h](/src/displayapp/screens/settings/Settings.h). You should now be able to [build](../buildAndProgram.md) the firmware and flash it to your PineTime. Yay! diff --git a/doc/gettingStarted/itd-external-resources.png b/doc/gettingStarted/itd-external-resources.png Binary files differnew file mode 100644 index 00000000..b3ff99be --- /dev/null +++ b/doc/gettingStarted/itd-external-resources.png diff --git a/doc/gettingStarted/updating-software.md b/doc/gettingStarted/updating-software.md index d302607e..5c867023 100644 --- a/doc/gettingStarted/updating-software.md +++ b/doc/gettingStarted/updating-software.md @@ -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. + + + +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: + + |
