From 97668c775bb5e501b32fce2fc92f4a5995aec1b1 Mon Sep 17 00:00:00 2001 From: Eli Weiss Date: Sun, 5 Dec 2021 10:41:01 -0600 Subject: [PATCH] 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(-) 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: