diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/MemoryAnalysis.md | 22 | ||||
| -rw-r--r-- | doc/NavigationService.md | 4 | ||||
| -rw-r--r-- | doc/PinetimeStubWithNrf52DK.md | 12 | ||||
| -rw-r--r-- | doc/SPI-LCD-driver.md | 2 | ||||
| -rw-r--r-- | doc/SWD.md | 4 | ||||
| -rw-r--r-- | doc/ble.md | 4 | ||||
| -rw-r--r-- | doc/branches.md | 4 | ||||
| -rw-r--r-- | doc/buildAndProgram.md | 4 | ||||
| -rw-r--r-- | doc/code/Apps.md | 6 | ||||
| -rw-r--r-- | doc/code/Intro.md | 4 | ||||
| -rw-r--r-- | doc/contribute.md | 2 | ||||
| -rw-r--r-- | doc/gettingStarted/about-software.md | 10 | ||||
| -rw-r--r-- | doc/gettingStarted/gettingStarted-1.0.md | 2 | ||||
| -rw-r--r-- | doc/gettingStarted/ota-gadgetbridge.md | 2 | ||||
| -rw-r--r-- | doc/openOCD.md | 10 | ||||
| -rw-r--r-- | doc/ui_guidelines.md | 1 |
16 files changed, 47 insertions, 46 deletions
diff --git a/doc/MemoryAnalysis.md b/doc/MemoryAnalysis.md index 7304e3f3..376f98f6 100644 --- a/doc/MemoryAnalysis.md +++ b/doc/MemoryAnalysis.md @@ -32,13 +32,13 @@ In this analysis, I used [Linkermapviz](https://github.com/PromyLOPh/linkermapvi ### Linkermapviz -[Linkermapviz](https://github.com/PromyLOPh/linkermapviz) parses the MAP file and displays its content in a graphical way into an HTML page: +[Linkermapviz](https://github.com/PromyLOPh/linkermapviz) parses the MAP file and displays its content on an HTML page as a graphic:  -Using this tool, you can easily see the size of each symbol relative to the other one, and check what is using most of the space,... +Using this tool, you can compare the relative size of symbols. This can be helpful for checking memory usage at a glance. -Also, as Linkermapviz is written in Python, you can easily modify it to adapt it to your firmware, export data in another format,... For example, [I modified it to parse the contents of the MAP file and export it in a CSV file](https://github.com/InfiniTimeOrg/InfiniTime/issues/313#issuecomment-842338620). I could later on open this file in LibreOffice Calc and use sort/filter functionality to search for specific symbols in specific files... +Also, as Linkermapviz is written in Python, you can easily modify and adapt it to your firmware or export data in another format. For example, [here it is modified to parse the contents of the MAP file and export it in a CSV file](https://github.com/InfiniTimeOrg/InfiniTime/issues/313#issuecomment-842338620). This file could later be opened in LibreOffice Calc where sort/filter functionality could be used to search for specific symbols in specific files... ### Puncover [Puncover](https://github.com/HBehrens/puncover) is another useful tools that analyses the binary file generated by the compiler (the .out file that contains all debug information). It provides valuable information about the symbols (data and code): name, position, size, max stack of each functions, callers, callees... @@ -46,8 +46,8 @@ Also, as Linkermapviz is written in Python, you can easily modify it to adapt it Puncover is really easy to install: - - clone the repo and cd into the cloned directory - - setup a venv + - Clone the repo and cd into the cloned directory + - Setup a venv - `python -m virtualenv venv` - `source venv/bin/activate` - Install : `pip install .` @@ -60,13 +60,13 @@ Puncover is really easy to install: - Launch a browser at http://localhost:5000/ ### Analysis -Using the MAP file and tools, we can easily see what symbols are using most of the FLASH memory space. In this case, with no surprise, fonts and graphics are the biggest flash space consumer. +Using the MAP file and tools, we can easily see what symbols are using most of the flash memory. In this case, unsuprisingly, fonts and graphics are the largest use of flash memory.  -This way, you can easily check what needs to be optimized : we should find a way to store big static data (like fonts and graphics) in the external flash memory, for example. +This way, you can easily check what needs to be optimized. We should find a way to store big static data (like fonts and graphics) in the external flash memory, for example. -It's always a good idea to check the flash memory space when working on the project : this way, you can easily check that your developments are using a reasonable amount of space. +It's always a good idea to check the flash memory space when working on the project. This way, you can easily check that your developments are using a reasonable amount of space. ### Links - Analysis with linkermapviz : https://github.com/InfiniTimeOrg/InfiniTime/issues/313#issuecomment-842338620 @@ -210,7 +210,7 @@ NRF_LOG_INFO("heap : %d", m.uordblks); ``` #### Analysis -According to my experimentation, InfiniTime uses ~6000bytes of heap most of the time. Except when the Navigation app is launched, where the heap usage increases to... more than 9500 bytes (meaning that the heap overflows and could potentially corrupt the stack!!!). This is a bug that should be fixed in #362. +According to my experimentation, InfiniTime uses ~6000bytes of heap most of the time. Except when the Navigation app is launched, where the heap usage exceeds 9500 bytes (meaning that the heap overflows and could potentially corrupt the stack). This is a bug that should be fixed in #362. To know exactly what's consuming heap memory, you can `wrap` functions like `malloc()` into your own functions. In this wrapper, you can add logging code or put breakpoints: @@ -245,7 +245,7 @@ Using this technique, I was able to trace all malloc calls at boot (boot -> digi - https://www.embedded.com/mastering-stack-and-heap-for-system-reliability-part-3-avoiding-heap-errors/ ## LVGL -I did a deep analysis of the usage of the buffer dedicated for lvgl (managed by lv_mem). +I did a deep analysis of the usage of the buffer dedicated to lvgl (managed by lv_mem). This buffer is used by lvgl to allocated memory for drivers (display/touch), screens, themes, and all widgets created by the apps. The usage of this buffer can be monitored using this code : @@ -256,7 +256,7 @@ lv_mem_monitor(&mon); NRF_LOG_INFO("\t Free %d / %d -- max %d", mon.free_size, mon.total_size, mon.max_used); ``` -The most interesting metric is `mon.max_used` which specifies the maximum number of bytes that were used from this buffer since the initialization of lvgl. +The most interesting metric is `mon.max_used` which specifies the maximum number of bytes used from this buffer since the initialization of lvgl. According to my measurements, initializing the theme, display/touch driver and screens cost **4752** bytes! Then, initializing the digital clock face costs **1541 bytes**. For example a simple lv_label needs **~140 bytes** of memory. diff --git a/doc/NavigationService.md b/doc/NavigationService.md index fd81d0bf..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. The intended purpose is 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 @@ -22,7 +22,7 @@ This is a client supplied string describing the upcoming instruction such as "At This is a short string describing the distance to the upcoming instruction such as "50 m". ## Progress (UUID 00010004-78fc-48fe-8e23-433b3a1942d0) -The percent complete in a uint8. The watch displays this as an overall progress in a progress bar. +The percent complete in a uint8. The watch displays this as an overall progress in a progress bar. ## Full icon list * arrive diff --git a/doc/PinetimeStubWithNrf52DK.md b/doc/PinetimeStubWithNrf52DK.md index c4857921..dcaad69b 100644 --- a/doc/PinetimeStubWithNrf52DK.md +++ b/doc/PinetimeStubWithNrf52DK.md @@ -1,11 +1,11 @@ # Build a stub for PineTime using NRF52-DK -[NRF52-DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52-DK) is the official developpment kit for NRF52832 SoC from Nordic Semiconductor. +[NRF52-DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52-DK) is the official developpment kit for the NRF52832 SoC from Nordic Semiconductor used in the PineTime. -It can be very useful for PineTime development: - * You can use it embedded JLink SWD programmer/debugger to program and debug you 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 than the PineTime. +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 than the one you could 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 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 @@ -41,7 +41,7 @@ You just need to make the following connections: | P0.13 | Button IN (D3 in my case) | | GND | GND | -You also need to enable the I/O expander to disconnect pins from buttons and led on the NRF52-DK and leave them available on the pin headers: +You also need to enable the I/O expander to disconnect pins from the buttons and LED on the NRF52-DK and leave them available on the pin headers: | NRF52 -DK | NRF52- DK | | --------- | --------- | diff --git a/doc/SPI-LCD-driver.md b/doc/SPI-LCD-driver.md index f787aab7..29f3bbfa 100644 --- a/doc/SPI-LCD-driver.md +++ b/doc/SPI-LCD-driver.md @@ -1,6 +1,6 @@ # The SPI LCD driver ## Introduction -The LCD controller that drive the display of the Pinetime is the Sitronix ST7789V. This controller is easy to integrate with an MCU thanks to its SPI interface, and has some interesting features like: +The LCD controller that drives the display of the Pinetime is the [Sitronix ST7789V](https://wiki.pine64.org/images/5/54/ST7789V_v1.6.pdf). This controller is easy to integrate with an MCU thanks to its SPI interface, and has some interesting features like: - an on-chip display data RAM that can store the whole framebuffer - partial screen update - hardware assisted vertical scrolling @@ -4,9 +4,9 @@ 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 second, until the logo is completely drawn on the display. +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** @@ -120,11 +120,11 @@ Reading a value from the firmware version characteristic will yield a UTF-8 enco #### Battery Level -Reading from the battery level characteristic yields a single byte of data. This byte can be converted to an unsigned 8-bit integer which will be the battery percentage. This characteristic allows notify for updates as the value changes. +Reading from the battery level characteristic yields a single byte of data. This byte can be converted to an unsigned 8-bit integer which will be the battery percentage. This characteristic allows notifications for updates as the value changes. #### Heart Rate -Reading from the heart rate characteristic yields two bytes of data. I am not sure of the function of the first byte. It appears to always be zero. The second byte can be converted to an unsigned 8-bit integer which is the current heart rate. This characteristic also allows notify for updates as the value changes. +Reading from the heart rate characteristic yields two bytes of data. I am not sure of the function of the first byte. It appears to always be zero. The second byte can be converted to an unsigned 8-bit integer which is the current heart rate. This characteristic also allows notifications for updates as the value changes. --- diff --git a/doc/branches.md b/doc/branches.md index ef280f40..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. @@ -9,4 +9,4 @@ New features should be implemented in **feature branches** created from **develo To release a new version of the application, when develop is considered stable, a **release** branch is created from **develop**. This can be considered as a *release candidate* branch. When everything is OK, this release branch is merged into **master** and the release is generated (a tag is applied to git, the release note is finalized, binaries are built,...) from **master**. -Git flow also supports the creation of **hotfix** branches when a bug is discovered in a released version. The **hotfix** branch is created from **master** and will be used only to implement a fix to this bug. Multiple hotfix branches can be created for the same release if more than one bugs are discovered.
\ No newline at end of file +Git flow also supports the creation of **hotfix** branches when a bug is discovered in a released version. The **hotfix** branch is created from **master** and will be used only to implement a fix to this bug. Multiple hotfix branches can be created for the same release if multiple bugs are discovered.
\ No newline at end of file diff --git a/doc/buildAndProgram.md b/doc/buildAndProgram.md index 3686871a..feef9f6d 100644 --- a/doc/buildAndProgram.md +++ b/doc/buildAndProgram.md @@ -4,7 +4,7 @@ To build this project, you'll need: - A cross-compiler : [ARM-GCC (9-2020-q2-update)](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads/9-2020-q2-update) - The NRF52 SDK 15.3.0 : [nRF-SDK v15.3.0](https://developer.nordicsemi.com/nRF5_SDK/nRF5_SDK_v15.x.x/nRF5_SDK_15.3.0_59ac345.zip) - The Python 3 modules `cbor`, `intelhex`, `click` and `cryptography` modules for the `mcuboot` tool (see [requirements.txt](../tools/mcuboot/requirements.txt)) - - To to keep the system clean a python virtual environment (`venv`) can be used to install the python modules into + - To keep the system clean, you can install python modules into a python virtual environment (`venv`) ```sh python -m venv .venv source .venv/bin/activate @@ -260,4 +260,4 @@ Finally, merge them together with **mergehex**: This file must be flashed at offset **0x00** of the internal memory of the NRF52832. #### spinor.bin -This file is the MCUBoot image of the last stable version of the recovery firmware. It must be flashed at offset **0x00** of the external SPINOR flash memory.
\ No newline at end of file +This file is the MCUBoot image of the last stable version of the recovery firmware. It must be flashed at offset **0x00** of the external SPINOR flash memory. diff --git a/doc/code/Apps.md b/doc/code/Apps.md index b1c7d20e..f067b58b 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 reference. ### 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/contribute.md b/doc/contribute.md index b1be84a4..f2a4aeaa 100644 --- a/doc/contribute.md +++ b/doc/contribute.md @@ -46,7 +46,7 @@ Other contributors can post comments about the pull request, maybe ask for more Once the pull request is reviewed and accepted, it'll be merged into **develop** and will be released in the next version of the firmware. -## Why all these rules? +## Why all these rules? Reviewing pull requests is a **very time consuming task**. Everything you do to make reviewing easier will **get your PR merged faster**. 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  -Read carefully the warning and tap **Install**: +Read the warning carefully and tap **Install**:  diff --git a/doc/openOCD.md b/doc/openOCD.md index b3661cee..df24b30b 100644 --- a/doc/openOCD.md +++ b/doc/openOCD.md @@ -1,12 +1,12 @@ # OpenOCD and STLink OpenOCD (**Open O**n **C**hip **D**ebugger) is an open source tool that interfaces with many SWD/JTAG debugger to provide debugging and *in-system* programming for embedded target devices. -It supports the **NRF52** (the CPU of the PineTime) and the **STLinkV2**, a cheap SWD debugger. +OpenOCD supports the **NRF52** (the CPU of the PineTime) and the **STLinkV2**, a cheap SWD debugger. -It works on X86 computers, as well as ARM/ARM64 computers and SBC (like the RaspberryPi and Pine64 Pinebook Pro) ! +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 most of the time 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: @@ -27,7 +27,7 @@ sudo cp contrib/60-openocd.rules /etc/udev/rules.d/ sudo udevadm control --reload-rules ``` - - You can now plug your STLinkV2 in a USB port and run OpenOCD to see if it's working correctly: + - You can now plug your STLinkV2 into a USB port and run OpenOCD to see if it's working correctly: ``` $ openocd -f interface/stlink.cfg -f target/nrf52.cfg @@ -63,7 +63,7 @@ gdb_breakpoint_override hard source [find target/nrf52.cfg] ``` -This file specifies to OpenOCD which debugger and target it will be connected to.. +This file specifies to OpenOCD which debugger and target it will be connected to. Then, we use various *user files* to use OpenOCD to flash InfiniTime binary files. diff --git a/doc/ui_guidelines.md b/doc/ui_guidelines.md index 0cbd39f5..296497af 100644 --- a/doc/ui_guidelines.md +++ b/doc/ui_guidelines.md @@ -9,5 +9,6 @@ - Top bar takes at least 20px + padding - Top bar right icons move 8px to the left when using a page indicator - A black background helps to hide the screen border, allowing the UI to look less cramped when utilizing the entire display area. +- A switch should be twice as wide as it is tall.  |