From 96267e3dc4e5f0281d44bd922fe6ee371d3fb30c Mon Sep 17 00:00:00 2001 From: Adam Dobrowolski Date: Tue, 15 Mar 2022 08:13:52 +0100 Subject: [PATCH] [MOS-281] Apply suggestions from code review Co-authored-by: Bartosz Cichocki --- doc/build_targets.md | 2 +- doc/development_workflow.md | 2 +- doc/download_assets.md | 6 ++-- doc/quickstart.md | 42 ++++++++++++------------ doc/running_on_phone.md | 27 +++++++-------- products/PurePhone/ProductKeyFeatures.md | 4 +-- 6 files changed, 42 insertions(+), 41 deletions(-) diff --git a/doc/build_targets.md b/doc/build_targets.md index 857b7a6eb0409af3f11e3636fd2e603250e7a7e8..7471780397b2a8702e7b613cd5d59c770183b020 100644 --- a/doc/build_targets.md +++ b/doc/build_targets.md @@ -50,7 +50,7 @@ Image of the software to be loaded onto the device memory. Has all necessary dat The disk image can be built with additional, development assets. Please look for `WITH_DEVELOPMENT_FEATURES` for more information in make. **All disk images can be inspected** to do so you can: -1. use losetup to add loop device for created image i.e.: +1. use `losetup` to add loop device for created image i.e.: ``` sudo losetup --show --partscan -f /path/to/file ``` diff --git a/doc/development_workflow.md b/doc/development_workflow.md index a74c6514a7a7c4c15c2cbae659c4f60811976a07..8b8797aa9f5bcb1a05a02f4a74206580216b6d7d 100644 --- a/doc/development_workflow.md +++ b/doc/development_workflow.md @@ -95,7 +95,7 @@ All PRs are checked against a series of checks on CI: - linux targets - linux unittests -Passing the CI is required element to be able to integrate the changes. +Passing the CI is a required element to be able to integrate the changes. ## Merge to `master` branch diff --git a/doc/download_assets.md b/doc/download_assets.md index 0a251b7016f64f8312af27168185ff392d2d8492..069ab74d13b861d9773d86e9d22566565c387246 100644 --- a/doc/download_assets.md +++ b/doc/download_assets.md @@ -28,12 +28,12 @@ For downloading assets, we need a ":repo" scope with all sub-scopes. **Note:** Tokens are displayed only during their creation, so this is the only moment you can copy them. If you forget to do this, you will have to generate a new token. -**Note:** With token added [please double check](#Testing-for-proper-asset-download-configuration), if it's working before issuing not working toolkit as most of the problems lies with no, or improper configuration. +**Note:** With token added [please double check](#Testing-for-proper-asset-download-configuration) if it's working before issuing not working toolkit as most of the problems lies with no, or improper configuration. ## Storing settings -The `download_assets.py` loads authorisation data via git configuration. -The process requires so that this data isstored in your current repository or global git configuration. +The `download_assets.py` loads authorization data via git configuration. +The process requires that this data is stored in your current repository or global git configuration. To do so: Add you github login to the git config: diff --git a/doc/quickstart.md b/doc/quickstart.md index 1b9c325628c2f581778d099993c77e3793cfee0c..4314867d2048f0c186965688012b1ab4cf18bf26 100644 --- a/doc/quickstart.md +++ b/doc/quickstart.md @@ -34,7 +34,7 @@ The project can be build: - on linux - on windows with [WSL](https://docs.microsoft.com/en-us/windows/wsl/) - with docker image -- Mac native compilation **is not supported** +Note: Mac native compilation **is not supported** ### Download repository and submodules @@ -42,7 +42,7 @@ MuditaOS uses submodules, therefore for clone use: ``` git clone --recurse-submodules git@github.com:mudita/MuditaOS.git ``` -if you didin't use `--recurse-submodules` or have to update submodules use: +if you didn't use `--recurse-submodules` or have to update submodules use: ``` git submodule update --init --recursive ``` @@ -58,10 +58,10 @@ cd config && ./bootstrap.sh 0- The script is written for Ubuntu and tested on 20.04. -**Note** that this: -- the script require sudo to: - - downloads a shellscript from `get.docker.com` and runs it with sudo for Docker installation. - - instals few required packages (list them with: `cat config/bootstrap_config`) which also require root privileges. +**Note** The script: +-requires sudo to: + - downloads a shell script from `get.docker.com` and runs it with sudo for Docker installation. + - installs a few required packages (list them with: `cat config/bootstrap_config`) which also require root privileges. - installs `GCCv10` and `CMake` to `$HOME` directory. - it's needed to be run only once @@ -96,9 +96,9 @@ ex.: We are using J-Link driver in version J-Link v634f ([Ubuntu download](https://www.segger.com/downloads/jlink/JLink_Linux_V634f_x86_64.deb)) -**NOTE:** This step is only required to load software and debug it via J-Link. It's not available for community - as it requires a programator board and soldered in programmator socket. +**NOTE:** This step is only required to load software and debug it via J-Link. It's not available for the community - as it requires a programmer board and soldered in programmer socket. -**WARNING:** newer J-Link software revisions seem to work fine, but loading via them do not result in usable software on the hardware tharget. +**WARNING:** newer J-Link software revisions seem to work fine, but loading via them does not result in usable software on the hardware target. #### Add GitHub token @@ -108,9 +108,9 @@ Please follow github token configuration here: [download assets documentation](. #### Project configuration To configure project we have helper script: `./configure.sh` which essentially passes through basic cmake configuration for each product for each platform. -We hihly advice to use `ninja` as it has proven better compilation times over make. +We highly advise using `ninja` as it has proven better compilation times over make. -which can be run with following parameters: +which can be run with the following parameters: ``` # command # product # platform # build type ./configure.sh [PurePhone|BellHybrid] [rt1051|linux] [release|debug|relwithdebinfo] [additional cmake parameters and options go here, i.e. -DENABLE_DEVELOPER_MODE_ENDPOINT=1 or "-G Ninja"] @@ -118,15 +118,15 @@ which can be run with following parameters: __Examples:__ -1. building pure phone for rt1051 platform with ninja +1. building PurePhone for rt1051 platform with ninja -**NOTE** Due to software size we cant have full debug builds for rt1051 targets. Please use relwithdebinfo +**NOTE** Due to software size we can't have full debug builds for rt1051 targets. Please use relwithdebinfo ``` ./configure.sh pure rt1051 relWithDebInfo "-G Ninja" ``` -2. building pure phone for linux platform with make +2. building PurePhone for Linux platform with make ``` ./configure.sh pure linux debug @@ -140,24 +140,24 @@ __Examples:__ #### Project build -Each run of `configure.sh` created `build-{PRODUCT}-{PLATFORM}-{OPTMALIZAION}` folder, i.e.: `build-PurePhone-rt1051-RelWithDebInfo` +Each run of `configure.sh` creates `build-{PRODUCT}-{PLATFORM}-{OPTMALIZAION}` folder, i.e.: `build-PurePhone-rt1051-RelWithDebInfo` 1. enter your selected build catalog 2. run `ninja` or `make` depending on your selection during configuration. 3. This will compile your selected target and create image of it To know more about build targets please see: [build targets documentation](../doc/build_targets.md) -**WARNING:** our source code is open source, but the project itself is in progress of fully embracing the community. Currently you can: -1. build binaries from the software -2. are not able to create images - due difficulties with separation of 3rd party propritetary assets +**WARNING:** our source code is open source, but the project itself is in the progress of fully embracing the community. Currently you: +1. can build binaries from the software +2. are not able to create images - due to difficulties with separation of 3rd party proprietary assets **Note** You can install and use ccache to speed up compilations #### Project load and run -Project load and run is platform dependent. Curently we suport only linux and rt1051 targets. +Project load and run are platform-dependent. Currently, we support only Linux and rt1051 targets. -**NOTE:** Addition of open source assets is in progress and should be done in following weeks. Till then Open source community cant build their own images - due to lack od fonts and luts. Support will be added step by step: +**NOTE:** Addition of open source assets is in progress and should be done in the following weeks. Till then Open source community can't build their own images - due to a lack of fonts and LUTs. Support will be added step by step: - addition of open source fonts - addition of partial update packages (not signed) for Open Source contributors @@ -171,12 +171,12 @@ Please follow: [running on rt1051 platform](./running_on_phone.md) ### checking commits -All commits have to compy with checks with: +All commits have to comply with checks with: 1. our pre commit hook 1.1 required code have to be copyrighted with Mudita licensing 1.2 required code have to comply to clang-format defined in repository 1.3 code is checked against addition of binary blobs polluting software -2. pre merge CI job checking if commit is in acceptable format: +2. pre-merge CI job checking if the commit is in acceptable format: See [development workflow](./development_workflow.md) for more information diff --git a/doc/running_on_phone.md b/doc/running_on_phone.md index 7ebe53d6ac5340d8cee2e02554d3a829cb480ea7..ca95faef1597da22471a79e5350e60e5d9f44825 100644 --- a/doc/running_on_phone.md +++ b/doc/running_on_phone.md @@ -47,11 +47,12 @@ Files required to boot from eMMC are: On linux you can use: 1. `pureflash` -Fastest command to burn image into the eMMC card `sudo pureflash /dev/sdX` **Note:** Replace `/dev/sdX` with the disk name you found for your phone after connecting it to your computer. +The fastest command to burn image into the eMMC card: `sudo pureflash /dev/sdX` +**Note:** Replace `/dev/sdX` with the disk name you found for your phone after connecting it to your computer. 2. `dd` or `etcher` -You can use any raw memory copy tool such as `dd` or `etcher` which will transfer whole image built to the device memory. It will take much longer because it will copy whole 16GB memory. +You can use any raw memory copy tool such as `dd` or `etcher` which will transfer the whole image built to the device memory. It will take much longer because it will copy the whole 16GB of memory. dd example: ``` sudo dd if=./PurePhone.img of=/dev/sdb bs=1M status=progress conv=fsync 13:48:22 @@ -60,27 +61,27 @@ sudo dd if=./PurePhone.img of=/dev/sdb bs=1M status=progress conv=fsync On MacOS you can use script: - `./tools/macflash.sh` -**NOTE:** Devices in the field have direct eMMC via bootloader locked. +**NOTE:** End-user devices have direct access to the eMMC locked in bootloader. -#### via uptader utility +#### via updater utility -Every device is loaded with additional update software which is capable of updating any software package onto the device, while keeping last software backup. -Updater utility is the only normal way to update devices running in field and is used by MuditaCenter. +Every device is loaded with additional updater software which is capable of updating any software package onto the device while keeping the last software as a backup. +Updater utility is the only normal way to update devices running in-field and is used by Mudita Center. -**NOTE:** Porviding a minimum viable update package and utility for Open Source community is on our backlog. It can be created by trimming additional developemnt api from: -[updater feature tests](https://github.com/mudita/QAMuditaOS/tree/master/scenarios/updater). You can ask for development version of MuditaCentre with "update from file" capability enabled. +**NOTE:** Providing a minimum viable update package and utility for the Open Source community is on our backlog. It can be created by trimming additional development API from: +[updater feature tests](https://github.com/mudita/QAMuditaOS/tree/master/scenarios/updater). You can ask for the development version of Mudita Center with "update from file" capability enabled. -Update packede is defined here: [build targets](./build_targets.md) +Update package is described here: [build targets](./build_targets.md) ## How to mount Mudita Pure as a USB MSC -**NOTE:** all phones in field have eMMC access locked with password, following documentation is only for development devices or ones with eMMC unlocked or bypassed. +**NOTE:** all phones in field have eMMC access locked with a password, the following documentation is only for development devices or ones with eMMC unlocked or bypassed. -There are two ways to mount the phone as a USB MSC to access full access to the memory - using a bootloader or Ozone debugger. +There are two ways to mount the phone as a USB MSC to gain full access to the memory - using a bootloader or Ozone debugger. ### Mounting using a bootloader -**NOTE:** Devices in field have password blocked bootloaders. This is by design - normal users shouldn't ever require access to raw eMMC. +**NOTE:** Devices in field have password-locked bootloaders. This is by design - normal users shouldn't ever require access to raw eMMC. - hold center button (selection) - reset the device, either: @@ -101,4 +102,4 @@ We can have 3 types of partitions: - EXT4 - LittleFS -Both fat and ext4 can be mointed nativelly on linux, ext4 needs additional drivers on MacOS. To access LittleFS you need to mount it via FUSE using the following command `lfsfuse /dev/sdX --block_size=32768` +Both FAT and ext4 can be mounted natively on Linux, ext4 needs additional drivers on macOS. To access LittleFS you need to mount it via FUSE using the following command `lfsfuse /dev/sdX --block_size=32768` diff --git a/products/PurePhone/ProductKeyFeatures.md b/products/PurePhone/ProductKeyFeatures.md index 3011f5cd8d06ad036499a4cc18dea0aa5a198113..024deef0d0dd84207fb50d52a15f050c7e0ae022 100644 --- a/products/PurePhone/ProductKeyFeatures.md +++ b/products/PurePhone/ProductKeyFeatures.md @@ -11,9 +11,9 @@ PurePhone product key features - alarm clock - contacts and calendar synchronization via Mudita Center desktop app - flashlight -- user interface optimized for E Ink displays with frontlight support +- user interface optimized for E-Ink displays with front light support - dark mode -- Bluetooth headset connectivity with A2DP (Advanced Audio Distribution Profile) and HSP (Headset Profile) support +- Bluetooth headset connectivity with A2DP (Advanced Audio Distribution Profile) and HFP (Hands-free Profile) support - Passive Dual SIM support - USB-C Fast Charging - VoLTE and internet tethering support