From c12fc5e3132f88e2b134f9feed70a8bc1cae5e7f Mon Sep 17 00:00:00 2001 From: Riku Isokoski Date: Mon, 8 Nov 2021 18:11:29 +0200 Subject: Improvements to Apps.md and Intro.md --- doc/code/Apps.md | 43 ++++++++++++++++++------------------------- 1 file changed, 18 insertions(+), 25 deletions(-) (limited to 'doc/code/Apps.md') diff --git a/doc/code/Apps.md b/doc/code/Apps.md index 7c2d7a05..b8e4a3f4 100644 --- a/doc/code/Apps.md +++ b/doc/code/Apps.md @@ -1,11 +1,12 @@ # Apps This page will teach you: -- what apps in InfiniTime are +- what screens and apps are in InfiniTime - how to implement your own app ## Theory -Apps are the things you can launch from the app selection you get by swiping up. -At the moment, settings and even the app launcher itself or the clock are implemented very similarly, this might change in the future though. + +The user interface of InfiniTime is made up of **screens** +Screens that are opened from the app launcher are considered **apps** Every app in InfiniTime is it's own class. An instance of the class is created when the app is launched and destroyed when the user exits the app. They run inside the "displayapp" task (briefly discussed [here](./Intro.md)). @@ -23,27 +24,21 @@ it does not need to override any of these functions, as LVGL can also handle tou If you have any doubts, you can always look at how the other apps are doing things. ### Continuous updating -If your app needs to be updated continuously, yo can do so by overriding the `Refresh()` function in your class +If your app needs to be updated continuously, you can do so by overriding the `Refresh()` function in your class and calling `lv_task_create` inside the constructor. -An example call could look like this:
-`taskRefresh = lv_task_create(RefreshTaskCallback, LV_DISP_DEF_REFR_PERIOD, LV_TASK_PRIO_MID, this);`
-With `taskRefresh` being a member variable of your class and of type `lv_task_t*`. -Remember to delete the task again using `lv_task_del`. -The function `RefreshTaskCallback` is inherited from screen and just calls your `Refresh` function. -### Apps with multiple screens -InfiniTime provides a mini-library in [displayapp/screens/ScreenList.h](/src/displayapp/screens/ScreenList.h) -which makes it relatively easy to add multiple screens to your app. -To use it, #include it in the header file of your app and add a ScreenList member to your class. -The template argument should be the number of screens you need. -You will also need to add `CreateScreen` functions that return `std::unique_ptr` -to your class, one for every screen you have. -There are still some things left to to that I won't cover here. -To figure them out, have a look at the "apps" ApplicationList, Settings and SystemInfo. +An example call could look like this: +```cpp +taskRefresh = lv_task_create(RefreshTaskCallback, LV_DISP_DEF_REFR_PERIOD, LV_TASK_PRIO_MID, this); +``` +With `taskRefresh` being a member variable of your class and of type `lv_task_t*`. +Remember to delete the task again using `lv_task_del`. +The function `RefreshTaskCallback` is inherited from `Screen` and just calls your `Refresh` function. ## Creating your own app -A minimal app could look like this:
+A minimal app could look like this: + MyApp.h: ```cpp #pragma once @@ -66,13 +61,13 @@ namespace Pinetime { MyApp.cpp: ```cpp -#include "MyApp.h" +#include "displayapp/screens/MyApp.h" #include "displayapp/DisplayApp.h" using namespace Pinetime::Applications::Screens; MyApp::MyApp(DisplayApp* app) : Screen(app) { - lv_obj_t* title = lv_label_create(lv_scr_act(), NULL); + lv_obj_t* title = lv_label_create(lv_scr_act(), nullptr); lv_label_set_text_static(title, "My test application"); lv_label_set_align(title, LV_LABEL_ALIGN_CENTER); lv_obj_align(title, lv_scr_act(), LV_ALIGN_CENTER, 0, 0); @@ -95,12 +90,10 @@ 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 your app to be launched from the regular app launcher, go to [displayapp/screens/ApplicationList.cpp](/src/displayapp/screens/ApplicationList.cpp). -Add your app 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.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). You should now be able to [build](../buildAndProgram.md) the firmware and flash it to your PineTime. Yay! Please remember to pay attention to the [UI guidelines](../ui_guidelines.md) -when designing an app that you want to include in mainstream InfiniTime. +when designing an app that you want to be included in InfiniTime. -- cgit v1.2.3-70-g09d2 From 3375c4e18764cd0ed1be8898a21695ff60540b22 Mon Sep 17 00:00:00 2001 From: Riku Isokoski Date: Mon, 8 Nov 2021 18:13:27 +0200 Subject: Add missing periods --- doc/code/Apps.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/code/Apps.md') diff --git a/doc/code/Apps.md b/doc/code/Apps.md index b8e4a3f4..b1c7d20e 100644 --- a/doc/code/Apps.md +++ b/doc/code/Apps.md @@ -5,8 +5,8 @@ This page will teach you: ## Theory -The user interface of InfiniTime is made up of **screens** -Screens that are opened from the app launcher are considered **apps** +The user interface of InfiniTime is made up of **screens**. +Screens that are opened from the app launcher are considered **apps**. Every app in InfiniTime is it's own class. An instance of the class is created when the app is launched and destroyed when the user exits the app. They run inside the "displayapp" task (briefly discussed [here](./Intro.md)). -- cgit v1.2.3-70-g09d2 From 97668c775bb5e501b32fce2fc92f4a5995aec1b1 Mon Sep 17 00:00:00 2001 From: Eli Weiss Date: Sun, 5 Dec 2021 10:41:01 -0600 Subject: Improved "Getting Started" readability Clarified ambiguous references, clarified phrasing --- doc/branches.md | 2 +- doc/code/Apps.md | 6 +++--- doc/code/Intro.md | 4 ++-- doc/gettingStarted/about-software.md | 10 +++++----- doc/gettingStarted/gettingStarted-1.0.md | 2 +- doc/gettingStarted/ota-gadgetbridge.md | 2 +- doc/openOCD.md | 2 +- 7 files changed, 14 insertions(+), 14 deletions(-) (limited to 'doc/code/Apps.md') diff --git a/doc/branches.md b/doc/branches.md index b06c10cc..3c86375f 100644 --- a/doc/branches.md +++ b/doc/branches.md @@ -1,7 +1,7 @@ # Branches The branching model of this project is based on the workflow named [Git flow](https://nvie.com/posts/a-successful-git-branching-model/). -It is based on 2 main branches: +The project is based on 2 main branches: - **master** : this branch is always ready to be deployed. It means that at any time, we should be able to build the branch and release a new version of the application. - **develop** : this branch contains the latest development that will be integrated in the next release once it's considered as stable. diff --git a/doc/code/Apps.md b/doc/code/Apps.md index b1c7d20e..0e6d13cf 100644 --- a/doc/code/Apps.md +++ b/doc/code/Apps.md @@ -8,8 +8,8 @@ This page will teach you: The user interface of InfiniTime is made up of **screens**. Screens that are opened from the app launcher are considered **apps**. Every app in InfiniTime is it's own class. -An instance of the class is created when the app is launched and destroyed when the user exits the app. -They run inside the "displayapp" task (briefly discussed [here](./Intro.md)). +An instance of the class is created when the app is launched, and destroyed when the user exits the app. +Apps run inside the "displayapp" task (briefly discussed [here](./Intro.md)). Apps are responsible for everything drawn on the screen when they are running. By default, apps only do something (as in a function is executed) when they are created or when a touch event is detected. @@ -21,7 +21,7 @@ A destructor is needed to clean up LVGL and restore any changes (for example re- App classes can override `bool OnButtonPushed()`, `bool OnTouchEvent(TouchEvents event)` and `bool OnTouchEvent(uint16_t x, uint16_t y)` to implement their own functionality for those events. If an app only needs to display some text and do something upon a touch screen button press, it does not need to override any of these functions, as LVGL can also handle touch events for you. -If you have any doubts, you can always look at how the other apps are doing things. +If you have any doubts, you can always look at how the other apps function for examples. ### Continuous updating If your app needs to be updated continuously, you can do so by overriding the `Refresh()` function in your class diff --git a/doc/code/Intro.md b/doc/code/Intro.md index bf68c7a5..23b3ade1 100644 --- a/doc/code/Intro.md +++ b/doc/code/Intro.md @@ -24,9 +24,9 @@ There are also other tasks that are responsible for Bluetooth ("ll" and "ble" in and periodic tasks like heartrate measurements ([heartratetask/HeartRateTask.cpp](/src/heartratetask/HeartRateTask.cpp)). While it is possible for you to create your own task when you need it, it is recommended to just add functionality to `SystemTask::Work()` if possible. -If you absolutely need to create another task, try to guess how much [stack space](https://www.freertos.org/FAQMem.html#StackSize) (in words/4-byte packets) +If you absolutely need to create another task, try to estimate how much [stack space](https://www.freertos.org/FAQMem.html#StackSize) (in words/4-byte packets) it will need instead of just typing in a large-ish number. -You can use the define `configMINIMAL_STACK_SIZE` which is currently set to 120 words. +You can use `configMINIMAL_STACK_SIZE` which is currently set to 120 words. ## Controllers Controllers in InfiniTime are singleton objects that can provide access to certain resources to apps. diff --git a/doc/gettingStarted/about-software.md b/doc/gettingStarted/about-software.md index b19a610f..e935d938 100644 --- a/doc/gettingStarted/about-software.md +++ b/doc/gettingStarted/about-software.md @@ -12,15 +12,15 @@ InfiniTime has three distinct firmwares: **OTA** (**O**ver **T**he **A**ir) refers to updating of the firmware over BLE (**B**luetooth **L**ow **E**nergy). This is a functionality that allows the user to update the firmware on their device wirelessly. -**DFU** (**D**evice **F**irmware **U**pdate) is the file format and protocol used to send the update of the firmware to the watch over-the-air. InfiniTime implement the (legacy) DFU protocol from Nordic Semiconductor (NRF). +**DFU** (**D**evice **F**irmware **U**pdate) is the file format and protocol used to send the update of the firmware to the watch over-the-air. InfiniTime implements the (legacy) DFU protocol from Nordic Semiconductor (NRF). ## Bootloader -Most of the time, the bootloader just runs without your intervention (update and load the firmware). +Most of the time, the bootloader just runs without your intervention (updating and loading the firmware). -However, you can enable 2 functionalities using the push button: +However, you can use the bootloader to rollback to the previous firmware, or load the recovery firmware using the push button: - - Push the button until the pine cone is drawn in **blue** to force the rollback of the previous version of the firmware, even if you've already validated the updated one - - Push the button until the pine cone is drawn in **red** to load the recovery firmware. This recovery firmware only provides BLE connectivity and OTA functionality. + - Press and hold the button until the pine cone is drawn in **blue** to force the rollback of the previous version of the firmware, even if you've already validated the current one. + - Press and hold the button until the pine cone is drawn in **red** to load the recovery firmware. This recovery firmware only provides BLE connectivity and OTA functionality. More info about the bootloader in [its project page](https://github.com/JF002/pinetime-mcuboot-bootloader/blob/master/README.md). diff --git a/doc/gettingStarted/gettingStarted-1.0.md b/doc/gettingStarted/gettingStarted-1.0.md index 30b8bdb0..890164fe 100644 --- a/doc/gettingStarted/gettingStarted-1.0.md +++ b/doc/gettingStarted/gettingStarted-1.0.md @@ -18,7 +18,7 @@ You can sync the time using companion apps. You can also set the time in the settings without a companion app. (version >1.7.0) -InfiniTime doesn't handle daylight savings automatically, so make sure to set the correct the time or sync it with a companion app +InfiniTime doesn't handle daylight savings automatically, so make sure to set the correct the time or sync it with a companion app. ### Digital watch face diff --git a/doc/gettingStarted/ota-gadgetbridge.md b/doc/gettingStarted/ota-gadgetbridge.md index 022b5e4d..fe26c03b 100644 --- a/doc/gettingStarted/ota-gadgetbridge.md +++ b/doc/gettingStarted/ota-gadgetbridge.md @@ -18,7 +18,7 @@ Now that Gadgetbridge is connected to your PineTime, use a file browser applicat ![Gadgetbridge 3](gadgetbridge3.jpg) -Read carefully the warning and tap **Install**: +Read the warning carefully and tap **Install**: ![Gadgetbridge 4](gadgetbridge4.jpg) diff --git a/doc/openOCD.md b/doc/openOCD.md index a7386e34..df24b30b 100644 --- a/doc/openOCD.md +++ b/doc/openOCD.md @@ -6,7 +6,7 @@ OpenOCD supports the **NRF52** (the CPU of the PineTime) and the **STLinkV2**, a OpenOCD works on X86 computers, ARM/ARM64 computers, and SBCs (like the RaspberryPi and Pine64 Pinebook Pro)! ## Installation -We will build OpenOCD from sources, as packages from Linux distributions are often outdated and do not support the NRF52 correctly. +We will build OpenOCD from sources, as packages from Linux distributions are most of the time outdated and do not support the NRF52 properly. - Fetch the sources from GIT, and build and install it: -- cgit v1.2.3-70-g09d2 From ab059b90044981b0feb3f37201fcf6635d2c4e1f Mon Sep 17 00:00:00 2001 From: Eli Weiss Date: Sun, 5 Dec 2021 14:04:35 -0600 Subject: Revised documentation --- doc/NavigationService.md | 2 +- doc/PinetimeStubWithNrf52DK.md | 2 +- doc/SWD.md | 2 +- doc/code/Apps.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) (limited to 'doc/code/Apps.md') diff --git a/doc/NavigationService.md b/doc/NavigationService.md index b24a03b7..5a4f69e0 100644 --- a/doc/NavigationService.md +++ b/doc/NavigationService.md @@ -1,6 +1,6 @@ # Navigation Service ## Introduction -The navigation ble service provides 4 characteristics to allow the the watch to display navigation instructions from a companion application. This service is intended to be used when performing some outdoor activities, for example running or cycling. +The navigation ble service provides 4 characteristics to allow the watch to display navigation instructions from a companion application. This service is intended to be used when performing some outdoor activities, for example running or cycling. The 4 characteristics are: flag (string) - Upcoming icon name diff --git a/doc/PinetimeStubWithNrf52DK.md b/doc/PinetimeStubWithNrf52DK.md index e85bd554..dcaad69b 100644 --- a/doc/PinetimeStubWithNrf52DK.md +++ b/doc/PinetimeStubWithNrf52DK.md @@ -5,7 +5,7 @@ This development kit can be very useful for PineTime development: * You can use its embedded JLink SWD programmer/debugger to program and debug your code on the PineTime * As it's based on the same SoC than the PineTime, you can program it to actually run the same code as the PineTime. -This page is about the 2nd point : we will build a stub that will allow us to run the same code you can run on the PineTime. This will allow you to work more easily if you don't have a PineTime dev kit around, if you don't want to modify your dev kit for SWD programming, or if you want to use some feature from the NRF52-DK (like power measurement). +This page is about the 2nd point. We will build a stub that will allow us to run the same code you can run on the PineTime. This will allow you to work more easily if you don't have a PineTime dev kit around, if you don't want to modify your dev kit for SWD programming, or if you want to use some feature from the NRF52-DK (like power measurement). This stub only implements the display, the button and the BLE radio. The other features from the pintime are missing: * heart rate sensor diff --git a/doc/SWD.md b/doc/SWD.md index 668eaa5c..155983b3 100644 --- a/doc/SWD.md +++ b/doc/SWD.md @@ -6,7 +6,7 @@ Download the files **bootloader.bin**, **image-x.y.z.bin** and **pinetime-graphi The bootloader reads a boot logo from the external SPI flash memory. The first step consists of flashing a tool in the MCU that will flash the boot logo into this SPI flash memory. This first step is optional but recommended (the bootloader will display garbage on screen for a few second if you don't do it). Using your SWD tool, flash **pinetime-graphics-x.y.z.bin** at offset **0x0000**. Reset the MCU and wait for a few seconds until the logo is completely drawn on the display. -Then, using your SWD tool. Flash those file at specific offset: +Then, using your SWD tool, flash these file at the following offsets: - bootloader.bin : **0x0000** - image-x.y.z.bin : **0x8000** diff --git a/doc/code/Apps.md b/doc/code/Apps.md index 0e6d13cf..f067b58b 100644 --- a/doc/code/Apps.md +++ b/doc/code/Apps.md @@ -21,7 +21,7 @@ A destructor is needed to clean up LVGL and restore any changes (for example re- App classes can override `bool OnButtonPushed()`, `bool OnTouchEvent(TouchEvents event)` and `bool OnTouchEvent(uint16_t x, uint16_t y)` to implement their own functionality for those events. If an app only needs to display some text and do something upon a touch screen button press, it does not need to override any of these functions, as LVGL can also handle touch events for you. -If you have any doubts, you can always look at how the other apps function for examples. +If you have any doubts, you can always look at how the other apps function for reference. ### Continuous updating If your app needs to be updated continuously, you can do so by overriding the `Refresh()` function in your class -- cgit v1.2.3-70-g09d2