A .github/pull_request_template.md => .github/pull_request_template.md +12 -0
@@ 0,0 1,12 @@
+**Description**
+
+Please describe your pull request
+
+**Your checklist for this pull request**
+
+Make sure that this PR:
+- [ ] Complies with our guidelines for contributions
+- [ ] Has unit tests if possible.
+- [ ] Has documentation updated
+
+Thanks for your work ♥
M README.md => README.md +11 -64
@@ 6,58 6,23 @@ MuditaOS is a mobile operating system optimized for E Ink displays. Built on Fre
-## Key features
-
-- 3 modes (offline, do not disturb, connected) with magnetometer support
-- approved contacts list
-- threaded messaging with templates, drafts, UTF8 and basic emoji support
-- audio player supporting MP3, WAV, FLAC formats and indexed ID3 Tags
-- meditation app
-- calendar app
-- calculator
-- alarm clock
-- contacts and calendar synchronization via Mudita Center desktop app
-- flashlight
-- user interface optimized for E Ink displays with frontlight support
-- dark mode
-- Bluetooth headset connectivity with A2DP (Advanced Audio Distribution Profile) and HSP (Headset Profile) support
-- Passive Dual SIM support
-- USB-C Fast Charging
-- VoLTE and internet tethering support
-- HAL (Hardware Abstraction Layer) between the hardware and the OS
-- system manager that restores the system after switching on the device or performs the initial start-up
-- application manager for managing application lifecycle
-- SQLite database for storing contacts and notes
-- VFS (Virtual File System) + file storage based on `lwext4`
-- MTP (Media Transfer Protocol) support
+## Products
+
+There are two released products based on MuditaOS:
+1. [PurePhone](https://store.mudita.com/mudita-pure-minimalist-phone) - low distraction phone with rich [key features](./products/PurePhone/ProductKeyFeatures.md)
+2. [Mudita Harmony](https://store.mudita.com/mudita-harmony-your-healthy-bedtime-habits) - eink based distraction free alarm clock.
## Table of contents
-* [Quickstart](#Quickstart)
* [Contributing](#Contributing)
* [Discussions](#Discussions)
* [Reporting issues and feature requests](#Reporting-bugs-and-feature-requests)
* [Internationalization](#Internationalization)
+ * [Development environment setup](#development-envioronment-setup)
* [Development workflow](#Development-workflow)
* [Documentation](#documentation)
- * [How to generate documentation using Doxygen](#How-to-generate-documentation-using-Doxygen)
- * [Build targets supported by MuditaOS](./doc/build_targets.md)
* [License](#license)
-## Quickstart
-
-You can quickstart the project by going through one of the following guides:
-
-- [Quickstart](./doc/quickstart.md#Quickstart)
- - [Quickstart using Docker](./doc/quickstart.md#quickstart-using-docker)
- - [Building your own Docker image](./doc/quickstart.md#building-your-own-docker-image)
- - [Quickstart in your local environment](./doc/quickstart.md#quickstart-in-your-local-environment)
- - [Super dirty quickstart on Linux](./doc/quickstart.md#super-dirty-quickstart-on-linux)
- - [Super dirty quickstart with unit tests](./doc/quickstart.md#super-dirty-quickstart-with-unit-tests)
- - [Super dirty quickstart on the phone](./doc/quickstart.md#super-dirty-quickstart-on-the-phone)
- - [Preparing packages](./doc/quickstart.md#preparing-packages)
-- [How to use Logging engine](./module-utils/log/doc/logging_engine.md)
-
## Contributing
Pull requests are welcome. Please follow the guidelines in the ["Contributing to MuditaOS"](./CONTRIBUTING.md) article. Before contributing or starting a discussion, please make sure that you read our [Code of Conduct](./CODE_OF_CONDUCT.md).
@@ 74,6 39,10 @@ You can report bugs and feature requests on [GitHub](https://github.com/mudita/M
If you want to start localizing MuditaOS interface please start from [the "Internationalization" article](./doc/i18n.md).
+### Development environment setup
+
+To develop MuditaOS please follow guide on [environment setup](./doc/quickstart.md#Quickstart)
+
### Development workflow
When contributing code or documentation changes please follow the guidleines inside the ["Development workflow"](./doc/development_workflow.md) article.
@@ 84,31 53,9 @@ For everything you need to kickstart your development environment please go to t
A fully detailed documentation can be build locally using [Doxygen](https://www.doxygen.nl/index.html).
-### How to generate documentation using Doxygen
-
-You can build code documentation with the following command, regarding the product:
-
-```bash
-./configure (PurePhone|BellHybrid) linux Debug
-cd build-(PurePhone|BellHybrid)-linux-Debug
-make doc
-```
-If you prefer to build documentation always with `all` target instead, configure `cmake`
-with `BUILD_DOC_WITH_ALL` option set to `ON`, e.g.:
-
-```bash
-./configure <product> <target> <build_type> -DBUILD_DOC_WITH_ALL=ON
-```
-
-Documentation is generated in the `doc/html` subdirectory of the build directory. To view it open `index.html` using a web browser, e.g.:
-
-```bash
-firefox build-<target>-<build_type>/doc/html/index.html
-```
-
## Changelog
-The [MuditaOS changelog](./changelog.md) is regularly updated by the core development team.
+The [MuditaOS changelog](./changelog.md) is not regularly updated by the core development team.
## License
MuditaOS is licensed under [GNU GPLv3](https://choosealicense.com/licenses/gpl-3.0/).
M doc/README.md => doc/README.md +50 -62
@@ 1,68 1,56 @@
-# MuditaOS Documentation
+MuditaOS Documentation
+======================
This folder contains the documentation of the MuditaOS.
-## How to generate documentation using Doxygen
-
-Fully detailed documentation can be built locally using [Doxygen](https://www.doxygen.nl/index.html).
-
-You can build code documentation with the following command:
-```sh
-make doc
-```
-If you prefer to build documentation always with `all` target instead, configure `cmake`
-with `BUILD_DOC_WITH_ALL` option set to `ON`, e.g.:
-```sh
-cmake -DBUILD_DOC_WITH_ALL=ON . build/
-```
-
-Documentation is generated in the `doc/html` subdirectory of the build directory. To view it open `index.html` using a web browser, e.g.:
-```sh
-firefox build/doc/html/index.html
-```
-
-## Table of contents
-
-- Getting Started Guides
- - [Getting Started](quickstart.md)
- - [Setting up integrated development environment](setup_ide.md)
- - [How to use Mudita Pure simulator](howto_simulator.md)
- - [Keybindings on Linux](host_keyboard_bindings.md)
- - [Running MuditaOS on a phone](running_on_phone.md)
- - [Windows and macOS - flashing Pure with image](flashing_win_macos.md)
- - [Test harness](../test/README.md)
- - [Tethering](tethering.md)
-
-- Developer Guides
- - [Coding Guidelines](./MuditaCppCodingGuidelines.md)
- - System architecture
- - Modules
- - Applications
- - [Desktop](../module-apps/application-desktop/doc/README.md)
- - [Notifications](../module-apps/apps-common/notifications/README.md)
- - [Audio](../module-audio/README.md)
- - [Bluetooth](../module-bluetooth/README.md)
- - Database
- - [Queries](../module-db/queries/README.md)
- - [Tables](../module-db/Tables/README.md)
- - [SMS and Contacts database](database_v2.md)
- - [Filesystem](../module-vfs/README.md)
- - [GUI](../module-gui/README.md)
- - [Modem](../module-cellular/modem/README.md)
- - [System](../module-sys/README.md)
- - Services
- - [Application Manager](../module-services/service-appmgr/doc/README.md)
- - [Bluetooth](../module-services/service-bluetooth/doc/readme.md)
- - [Cellular](../module-services/service-cellular/doc/README.md)
- - [Desktop](../module-services/service-desktop/README.md)
- - [GUI](../module-services/service-gui/doc/README.md)
- - Tools
- - [MapParser](https://github.com/mudita/misc-tools/blob/master/mapparser/README.md)
- - [PureGDB](https://github.com/mudita/misc-tools/blob/master/puregdb/README.md)
+## Developer guides
+
+- [Development environment](quickstart.md)
+- [Build targets supported by MuditaOS](./doc/build_targets.md)
+- [Setting up integrated development environment](setup_ide.md)
+- [How to use Mudita Pure simulator](howto_simulator.md)
+- [Keybindings on Linux](host_keyboard_bindings.md)
+- [Running MuditaOS on a phone](running_on_phone.md)
+- [Windows and macOS - flashing Pure with image](flashing_win_macos.md)
+- [Test harness](../test/README.md)
+- [Tethering](tethering.md)
+- [Coding Guidelines](./MuditaCppCodingGuidelines.md)
+
+## System documentation
+
+Documentation listed below is system documentation listed depending on where it is.
+
+- System architecture
+- Modules
+ - Applications
+ - [Application Desktop](../module-apps/application-desktop/doc/README.md)
+ - [Notifications](../module-apps/apps-common/notifications/README.md)
+ - [Audio](../module-audio/README.md)
+ - [Bluetooth](../module-bluetooth/README.md)
+ - Database
+ - [Queries](../module-db/queries/README.md)
+ - [Tables](../module-db/Tables/README.md)
+ - [SMS and Contacts database](database_v2.md)
+ - [Filesystem](../module-vfs/README.md)
+ - [GUI](../module-gui/README.md)
+ - [Modem](../module-cellular/modem/README.md)
+ - [System](../module-sys/README.md)
+- Services
+ - [Application Manager](../module-services/service-appmgr/doc/README.md)
+ - [Bluetooth](../module-services/service-bluetooth/doc/readme.md)
+ - [Cellular](../module-services/service-cellular/doc/README.md)
+ - [Desktop](../module-services/service-desktop/README.md)
+ - [GUI](../module-services/service-gui/doc/README.md)
+- Utilities
+ - [How to use Logging engine](./module-utils/log/doc/logging_engine.md)
+- Tools
+ - [MapParser](https://github.com/mudita/misc-tools/blob/master/mapparser/README.md)
+ - [PureGDB](https://github.com/mudita/misc-tools/blob/master/puregdb/README.md)
- [Development workflow](development_workflow.md)
- - [Creating release](release.md)
- [Contributing](../CONTRIBUTING.md)
- [Internationalization](i18n.md)
-- Changelog
- - [HOWTO](changelog_howto.md)
- - [Latest changelog](../changelog.md)
+
+## Changelog
+- [HOWTO](changelog_howto.md)
+- [Latest changelog](../changelog.md)
+
M doc/build_targets.md => doc/build_targets.md +32 -0
@@ 23,6 23,7 @@ For each product there are targets:
| Arch | Name | Alias | Description |
|------|------|-------|-------------|
+|common| doc | | Target to build doxygen documentation, [documentation](./generate_doxygen.md) |
|common| \<Product\> | | Binary target for the product |
|common| \<Product\>-disk-img | \<Product\>.img | Disk image for the product |
|RT1051| \<Product\>-StandaloneImage | PurePhone-\<version\>-RT1051-package-standalone | Creates image that can be `dd` or `pureflash` to the device|
@@ 48,6 49,19 @@ Devices in the field have security keys burned, therefore an additional step - b
Image of the software to be loaded onto the device memory. Has all necessary data to properly run the OS.
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.:
+```
+sudo losetup --show --partscan -f /path/to/file
+```
+2. mount listed partitions as required
+3. remember to remove loop device after the use (where loopN is loop device created)
+```
+sudo losetup -d /dev/loopN
+```
+
+Or use `tools/mount_user_lfs_partition.py` which will do it for you.
+
## Update package
Tar-file meant to update software with the updater utility. It has all the necessary update assets and metadata.
@@ 58,6 72,23 @@ Currently, the update package has all of the base data that should be on the dev
Builds and executes all of the unit tests in the repository for the selected product.
Uses [download_assets](./download_assets.md) to download unit test's required assets (fonts)
+### Code coverage
+
+To generate code coverage reports for unit tests, you have to configure the project
+with `COVERAGE_ENABLE=ON`. Please note, that code coverage report generation
+works for the Linux/Debug configuration only.
+Code coverage reports are generated with the `gcovr` application. You can
+install it with:
+```
+pip3 install gcovr
+```
+
+Following targets related to coverage report generation are available:
+* `coverage-all-html` - run `ctest` and generate a detailed HTML report.
+* `coverage-html` - generate detailed HTML report based on the data collected during last execution of a unit test. The report
+will be generated in the `coverage-html` subdirectory of a build directory.
+* `coverage` - same as above, but generate an XML Cobertura report instead of an HTML.
+
## assets
Downloads Mudita private assets with [download_assets](./download_assets.md) that company is either not eligible or capable of sharing publicly.
@@ 78,3 109,4 @@ OS bootloader, used to pre-init hardware and launch either OS or updater utility
Downloads the updater with [download_assets](./download_assets.md).
Updater is used to perform the firmware upgrade via update packages.
+
M doc/development_workflow.md => doc/development_workflow.md +17 -1
@@ 77,9 77,25 @@ Include screenshots and gifs/screencasts if applicable. The more information you
During a PR review, team members will ask you questions regarding your solution. Please answer them by explaining the reasoning behind the suggested changes. Even if the feedback you receive regarding your PR is an obvious change, please answer with a simple OK to show that you haven't missed it.
+**NOTE:** do not close comments created by others without their clear approval. This makes reviewing PRs on github significanlty harder for reviewers.
+
## PR review - act on feedback
-Add changes to your PR that are requested by reviewers and push the feature branch once again. Update comments requesting changes with a simple `Done`. Don't resolve a discussion on your own, it's the reviewer's responsibility to do so.
+Add changes to your PR that are requested by reviewers and push the feature branch once again. Update comments requesting changes with a simple `Done`.
+
+**NOTE:** Again: don't resolve a discussion on your own. Wthout clear agreement or approval, it's the reviewer's responsibility to do so.
+
+## Pass the CI gate
+
+All PRs are checked against a series of checks on CI:
+- commit format
+- whole PR clang style check
+- compilations for every product in release with debug info or debug configurations for:
+ - rt1051
+ - linux targets
+ - linux unittests
+
+Passing the CI is required element to be able to integrate the changes.
## Merge to `master` branch
M doc/download_assets.md => doc/download_assets.md +19 -14
@@ 1,4 1,4 @@
-# Download Assets
+e Download Assets
Building update packages requires external assets located on external repositories releases pages, in specific versions for specified products. The tool automates downloading such assets.
@@ 16,7 16,11 @@ Please see `download_asset.py --help` for up to date parameters use and document
To use GitHub API your GitHub login and special token (API password) are required.
This token can by generated on "User" -> [Settings](https://github.com/settings/profile) page in section [Developer settings](https://github.com/settings/apps) -> [Personal acces tokens](https://github.com/settings/tokens) section.
-For more info please refer to the Github help page about adding tokens: [Creating a personal access token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token)
+It has to have at least read access to repositories.
+
+For more info please refer to the Github help page about adding tokens:
+[github documentation: Creating a personal access token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token)
+
### Scopes
When you generate a token you can set "Scopes" for which the token will work.
For downloading assets, we need a ":repo" scope with all sub-scopes.
@@ 24,23 28,24 @@ 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 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` file can have `login` and `password` passed through parameters,
-or this data can be stored in your current git repository configuration.
-Adding GitHub login to:
-```bash
-git config --add user.githublogin <login>
-```
+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.
-Adding API Token:
-```bash
-git config --add user.apitoken
+To do so:
+Add you github login to the git config:
+```
+git config --add user.githublogin Your_Github_Login_Here
+```
+Add token to your global git config on PC
+```
+git config --add --global user.apitoken Your_Generated_Token_Value_Here
```
-Checking the values:
+To see the values run:
```bash
git config user.githublogin
git config user.apitoken
@@ 53,7 58,7 @@ git config user.apitoken
git config user.apitoken
```
-**if not** please add the token ( see doc: [documentation](./doc/download_assets.md#github-api-token)
+**if not** please add the token ( see doc: [documentation](download_assets.md#github-api-token)
1. check if you have access to the PureUpdater repository in read mode
A doc/generate_doxygen.md => doc/generate_doxygen.md +26 -0
@@ 0,0 1,26 @@
+How to generate documentation using Doxygen
+=============================================
+
+**NOTE:** doxygen documentation is just another target.
+Basic targets documentation can be found [here](./build_targets.md).
+How to setup environment to be able to build the targets is here: [quickstart](./quickstart.md)
+
+
+Fully detailed doxygen documentation can be built locally using [Doxygen](https://www.doxygen.nl/index.html).
+
+You can build code documentation with the following command:
+```sh
+make doc
+```
+If you prefer to build documentation always with `all` target instead, configure `cmake`
+with `BUILD_DOC_WITH_ALL` option set to `ON`, e.g.:
+```sh
+cmake -DBUILD_DOC_WITH_ALL=ON . build/
+```
+
+Documentation is generated in the `doc/html` subdirectory of the build directory. To view it open `index.html` using a web browser, e.g.:
+```sh
+firefox build/doc/html/index.html
+```
+
+
M doc/quickstart.md => doc/quickstart.md +174 -125
@@ 1,49 1,185 @@
-# Quickstart
+# Development environment setup
+
+Table of Contents
+=================
+
+* [Development environment setup](#development-environment-setup)
+ * [Introduction](#introduction)
+ * [Download repository and submodules](#download-repository-and-submodules)
+ * [Install dependencies](#install-dependencies)
+ * [bootstrap](#bootstrap)
+ * [JLink software](#jlink-software)
+ * [Add GitHub token](#add-github-token)
+ * [Project configuration](#project-configuration)
+ * [Project build](#project-build)
+ * [Project load and run](#project-load-and-run)
+ * [Running on linux](#running-on-linux)
+ * [Running on rt1051 from emmc](#running-on-rt1051-from-emmc)
+ * [checking commits](#checking-commits)
+ * [CMake options](#cmake-options)
+ * [Catching logs using UART](#catching-logs-using-uart)
+ * [More details on preparing your local environment](#more-details-on-preparing-your-local-environment)
+ * [Code style with git hooks](#code-style-with-git-hooks)
+ * [Commit message template](#commit-message-template)
+ * [Commit message hook](#commit-message-hook)
+ * [Adding a hook:](#adding-a-hook)
+ * [Using a hook:](#using-a-hook)
+ * [Build using Docker](#build-using-docker)
+ * [Building your own Docker image](#building-your-own-docker-image)
+ * [Preparing packages](#preparing-packages)
-You can quickstart the project by going through one of the following guides:
+## Introduction
-- [Introduction](#introduction)
-- [CMake options](#CMake-options)
-- [Quickstart on Linux](#quickstart-on-linux)
-- [Quickstart with unit tests](#quickstart-with-unit-tests)
-- [Quickstart on the phone](#quickstart-on-the-phone)
-- [More details on preparing your local environment](#more-details-on-preparing-your-local-environment)
-- [CI build using Docker](#ci-build-using-docker)
-- [Building your own Docker image](#building-your-own-docker-image)
-- [Preparing packages](#preparing-packages)
+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**
-## Introduction
+### Download repository and submodules
-Run the provisioning script `./config/bootstrap.sh` to install all dependencies. The script is written for Ubuntu and tested on 20.04.
+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:
+```
+git submodule update --init --recursive
+```
-To run the script execute the following command: `cd config && ./bootstrap.sh 0-`
-Note that this downloads a shellscript from `get.docker.com` and runs it with sudo for Docker installation.
+### Install dependencies
-This script also installs few required packages (`cat config/bootstrap_config`) which also require root privileges.
+#### bootstrap
-Installation of `GCCv10` and `CMake` is done to `$HOME` directory.
+To install all the basic depenencies run:
+```
+cd config && ./bootstrap.sh 0-
+```
-Running the script without parameters will display a list of steps.
+The script is written for Ubuntu and tested on 20.04.
-After running provisioning you are ready to checkout and build project for both linux and RT1051. Please follow these steps:
+**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.
+- installs `GCCv10` and `CMake` to `$HOME` directory.
+- it's needed to be run only once
-1. Check out the project with submodules for the first time:
+After running provisioning you are ready to checkout and build project for both platforms supported.
-```bash
-git submodule update --init --recursive
+You can see this `help` if you do not pass any param to `bootstrap.sh`:
+```
+[I] ⋊> ~/w/m/M/config on master ⨯ ./bootstrap.sh 09:00:01
+test_if_run_as_root
+Available build steps:
+ 0 install_hooks
+ 1 add_ignore_revs_for_blame
+ 2 install_ubuntu_packages
+ 3 setup_arm_toolchain
+ 4 setup_cmake
+ 5 setup_gcc_alternatives
+ 6 add_to_path ARM_GCC /home/pholat/gcc-arm-none-eabi-10-2020-q4-major/bin
+ 7 add_to_path CMAKE /home/pholat/cmake-3.21.3-linux-x86_64/bin
+ 8 install_docker
+ 9 add_to_docker_group
+call:
+./bootstrap.sh <build step no>[-]
+ex.:
+./bootstrap.sh 1 - build step 1 (add_ignore_revs_for_blame)
+./bootstrap.sh 3 - build step 3 (setup_arm_toolchain)
+./bootstrap.sh 3- - build from step 3 to the end
+./bootstrap.sh 0- - build everything
```
-2. Update the repository with submodules
-```bash
-git pull --recurse-submodules
+#### JLink software
+
+
+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.
+
+**WARNING:** newer J-Link software revisions seem to work fine, but loading via them do not result in usable software on the hardware tharget.
+
+#### Add GitHub token
+
+We are storing assets on github pages and these are downloaded automatically before software images are built.
+Please follow github token configuration here: [download assets documentation](../doc/download_asset.py)
+
+#### 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.
+
+which can be run with 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"]
```
-3. Build the project for proper product:
-```bash
-./configure.sh [PurePhone|BellHybrid] [rt1051|linux] [release|debug|relwithdebinfo]
-cd build-[PurePhone|BellHybrid]-[rt1051|linux]-[release|debug|relwithdebinfo]
-make
+__Examples:__
+
+1. building pure phone for rt1051 platform with ninja
+
+**NOTE** Due to software size we cant 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
+
+```
+./configure.sh pure linux debug
```
+
+3. building bell for linux platform with ninja
+
+```
+./configure.sh bell linux debug "-G Ninja"
+```
+
+#### Project build
+
+Each run of `configure.sh` created `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
+
+**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.
+
+**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:
+- addition of open source fonts
+- addition of partial update packages (not signed) for Open Source contributors
+
+##### Running on linux
+
+Build default target and run `./PurePhone.elf` for phone target, or for BellHybrid: `./BellHybrid.elf`
+
+##### Running on rt1051 from emmc
+
+Please follow: [running on rt1051 platform](./running_on_phone.md)
+
+### checking commits
+
+All commits have to compy 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:
+
+See [development workflow](./development_workflow.md) for more information
+
### CMake options
Before configuring the project with `./configure.sh` you can tune it by enabling/disabling options to suite your needs.
This can be done manually, by editing the `.cmake` files (not recommended though) or by CLI/GUI tool like `ccmake`.
@@ 63,57 199,10 @@ This can be done manually, by editing the `.cmake` files (not recommended though
| `ENABLE_TEST_LOGS` | Enable logs in unit tests | OFF |
| `GENERATE_STACK_USAGE` | Generate stack usage report | OFF |
| `BUILD_DOC_WITH_ALL` | Build documentation with `all` target | OFF |
+| `SYSTEM_PROFILE` | Add MuditaOS x FreeRTOS proifling capability | OFF |
+| `WITH_DEVELOPMENT_FEATURES` | Enable all development features like access to test harness via USB | OFF |
By using `ENABLE_APP_X` (where `X` is the name of the application) you can enable/disable any application.
-### Quickstart on Linux
-
-Here's the bare minimum that will enable you to bootstrap the environment on Linux.
-
-```bash
-git submodule update --init --recursive # initialize submodules
-cd ./config/ && ./bootstrap.sh 0- && cd ../ # bootstrap requirements
-./configure.sh PurePhone|BellHybrid rt1051|linux Debug|Release|RelWithDebInfo # configure build
-cd <build-dir> # build dir depends on configuration
-make Pure # build
-./PurePhone.elf # run PurePhone - simulator screen will pop up (on the Linux filesystem)
-```
-
-If you want to run the simulator with image and our VFS implementation
-you need to run the image through the script:
-```bash
-./run_simulator_on_filesystem_image.sh
-```
-
-### Quickstart with unit tests
-
-After going through the Super dirty quickstart on Linux, run the following commands to build and run all unit tests:
-
-```bash
-./configure.sh PurePhone|BellHybrid linux debug
-cd <build-dir>
-make check
-```
-### Quickstart on the phone
-
-1. First install J-Link driver. We suggest using J-Link driver in version J-Link v634f ([Ubuntu download](https://www.segger.com/downloads/jlink/JLink_Linux_V634f_x86_64.deb))
-
-2. Please run the following commands:
-
-```bash
-cp ./env.cmake.sample ./env.cmake && sed -i "s:<HOME>:$HOME:" env.cmake
-git submodule update --init --recursive
-cd ./config/ && ./bootstrap.sh 0- && cd ../
-./configure.sh PurePhone|BellHybrid rt1051 RelWithDebInfo
-cd build-PurePhone|BellHybrid-rt1051-RelWithDebInfo
-make Pure
-
-```
-
-3. Please take the following steps in three parallel consoles/sessions:
-
- - Start J-Link server: `./StartJLinkServer.sh`
- - Load app with GDB via J-Link connected to Mudita Pure: `./run.sh <build folder> --product PurePhone`
- - Catch logs from Mudita Pure from J-Link RTT and write them to `/tmp/log.txt`: `JLinkRTTClient | tee /tmp/log.txt`
#### Catching logs using UART
@@ 127,31 216,6 @@ Please mind that logs on UART are more costly, so these might cause timing issue
## More details on preparing your local environment
-The quickest way to set up your environment is running the following command:
-```bash
-cd config && ./bootstrap.sh 0-
-```
-The script is written for Ubuntu and tested on 20.04.
-
-* This script will require `sudo` (for `apt`)
-* It will install `cmake` and `gcc` by default in `${HOME}` directory - in case of other needs, please change the script
-* The script doesn't install `ccache`, but if `ccache` is on the system - its support is added to `env.cmake.sample`
-* The script needs to be run only once
-
-If the script is run after a fresh `git clone` you need to update your git config (step 0 and 1).
-
-### `bootstrap.sh` steps, line by line
-
-* `./config/bootstrap.sh 0` - install style checking scripts to be automatically run on commit
-* `./config/bootstrap.sh 1` - `git blame` will ignore style changing commit
-* `./config/bootstrap.sh 2` - list packages required for setting up the environment *which are currently not installed*
-* `./config/bootstrap.sh 3` - set up arm toolchain, download and install it in home directory
-* `./config/bootstrap.sh 4` - set up `cmake`, download and install in home directory
-* `./config/bootstrap.sh 5` - list of commands required for switching default gcc/g++ to version 9
-* `./config/bootstrap.sh 6` - add paths for arm toolchain to your `PATH` environment variable - this is also used by `./env.cmake` *(this is required because `./env.cmake` uses environment variables set by this target)*
-* `./config/bootstrap.sh 7` - add paths for `cmake` to your `PATH` environment variable
-* `./config/bootstrap.sh 8` - install Docker
-
### Code style with git hooks
The `bootstrap.sh` script installs git hooks for code style checking. `pre-commit.hook`automatically updates style during commit. If you haven't run `bootstrap.sh` and want to use git hooks, you have to copy (or link) `pre-commit.hook` to your git config directory `.git/config/hooks`: `ln -s `pwd`/config/pre-commit.hook .git/hooks/pre-commit`
@@ 159,7 223,7 @@ The `bootstrap.sh` script installs git hooks for code style checking. `pre-commi
By default commit hook only checks if your changes have the appropriate style, if you would like to fix the style automatically during `git commit` you have to configure your git, by adding new variable `user.fixinstage` and setting it to `true` by running
`git config user.fixinstage true`
-If you prefer "notification than fix" workflow (so you can examine the changes), use the default hook behaviour (for notifications) and then call `./config/pre-commit.hook --fix`, this checks and fixes files in "stage", files that have status "changed" are not tested.
+If you prefer "notification then fix" workflow (so you can examine the changes), use the default hook behaviour (for notifications) and then call `./config/pre-commit.hook --fix`, this checks and fixes files in "stage", files that have status "changed" are not tested.
```bash
git commit
@@ 174,6 238,8 @@ git commit
To fix the style for Pull Request CI:
`./config/pre-commit.hook --branch-fix`
+Code style is done by clang
+
### Commit message template
To add a commit message template use this command:
@@ 183,7 249,7 @@ git config commit.template .gitmessage
```
This way each time you add a new commit you will see the template that will help
-you with the proper message format. More about that in [Development Workflow](./doc/development_workflow.md#commit-changes)
+you with the proper message format. More about that in [Development Workflow](development_workflow.md#commit-changes)
### Commit message hook
This hooks automatically converts your branch name to commit title
@@ 211,7 277,7 @@ Do your changes, and prepare commit
git commit
```
-## CI build using Docker
+## Build using Docker
You can build MuditaOS using a Docker container. To do that, follow these steps
1. Get Docker by running `./config/bootstrap.sh 8` or [install it yourself](https://www.docker.com/get-started) (if was not installed previously with `./config/bootstrap.sh 0-`).
@@ 270,21 336,4 @@ Please be aware that when building custom image you'll have to give it some tag
## Preparing packages
-If you need a package, containing everything needed to run the application, please check [build_targests.md](./doc/build_targests.md) document.
-
-## Generating code coverage reports
-
-To generate code coverage reports for unit tests, you have to configure the project
-with `COVERAGE_ENABLE=ON`. Please note, that code coverage report generation
-works for the Linux/Debug configuration only.
-Code coverage reports are generated with the `gcovr` application. You can
-install it with:
-```
-pip3 install gcovr
-```
-
-Following targets related to coverage report generation are available:
-* `coverage-all-html` - run `ctest` and generate a detailed HTML report.
-* `coverage-html` - generate detailed HTML report based on the data collected during last execution of a unit test. The report
-will be generated in the `coverage-html` subdirectory of a build directory.
-* `coverage` - same as above, but generate an XML Cobertura report instead of an HTML.
+If you need a package, containing everything needed to run the application, please check [build_targests.md](build_targests.md) document.
M doc/running_on_phone.md => doc/running_on_phone.md +63 -14
@@ 15,12 15,19 @@ Some assets can be omitted though e.g. for fonts the default fallback font will
An executable can be uploaded directly to the memory in an executable (image) form. J-Link GDB Server enables this. J-Link Server messages `"Download 15243 bytes…"` represent this way of running the executable. The binary is lost on reset and/or power loss. Booting from SDRAM doesn't involve bootloader.
-### Upload to SDRAM
+### Upload to SDRAM via J-Link
-You need to upload the `PurePhone.elf` file and then:
+You need to upload the `PurePhone.elf` file. To do so run in three parallel consoles/sessions:
-- Start J-Link Server with a script `./StartJLinkServer.sh` in a separate terminal/session.
-- Run the `./run.sh` script
+- Start J-Link server:
+ - For Mudita Pure: `./StartJLinkServer.sh`
+ - For BellHybrid: `./StartJLinkServer.sh T6`
+- Load app with GDB via J-Link connected:
+ - to Mudita Pure: `./run.sh <build folder> --product PurePhone`
+ - to BellHybrid: `./run.sh <build folder> --product BellHybrid`
+- Catch logs from Mudita Pure from J-Link RTT and write them to `/tmp/log.txt`: `JLinkRTTClient | tee /tmp/log.txt`
+
+**NOTE:** Running on phone is done via gdb, this way enables you to debug running target.
## eMMC (permanent)
@@ 35,21 42,63 @@ Files required to boot from eMMC are:
### Uploading it to the eMMC
-- Use the `pureflash` command to burn image into the eMMC card `sudo pureflash <PurePhone.img> /dev/sdX` **Note:** Replace `/dev/sdX` with the disk name you found for your phone after connecting it to your computer.
+#### via bootloader
+
+On linux you can use:
+1. `pureflash`
+
+Fastest command to burn image into the eMMC card `sudo pureflash <PurePhone.img> /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.
+dd example:
+```
+sudo dd if=./PurePhone.img of=/dev/sdb bs=1M status=progress conv=fsync 13:48:22
+```
+
+On MacOS you can use script:
+- `./tools/macflash.sh`
+
+**NOTE:** Devices in the field have direct eMMC via bootloader locked.
+
+#### via uptader 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.
+
+**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.
+
+Update packede is defined here: [build targets](./build_targets.md)
## How to mount Mudita Pure as a USB MSC
-There are two ways to mount the phone as a USB MSC - using a bootloader or Ozone debugger.
+**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.
+
+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.
### Mounting using a bootloader
-If you have a bootloader flashed and working use the following key combination, to mount Mudita Pure as MSC:
+**NOTE:** Devices in field have password blocked bootloaders. This is by design - normal users shouldn't ever require access to raw eMMC.
-- hold centre button (selection)
-- briefly press reset button (the one closest to the phone on the green breakout board)
-- wait while text scrolls from the bottom
+- hold center button (selection)
+- reset the device, either:
+ - briefly press reset button (the one closest to the phone on the green breakout board)
+ - detach USB and battery, then attach battery then USB
+- wait while text scrolls from the bottom - still holding the center button
- release centre button
-- press key 4
-
-FAT partition can be mounted directly by the Linux kernel. LittleFS partition can be mounted via
-FUSE using the following command `lfsfuse /dev/sdX <mount_point> --block_size=32768`
+- depending on bootloader:
+ - with eMMC locked:
+ - press 9
+ - input passkey
+ - confirm with left functional
+ - with eMMC not locked:
+ - press key 4
+
+We can have 3 types of partitions:
+- FAT
+- 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 <mount_point> --block_size=32768`
A products/PurePhone/ProductKeyFeatures.md => products/PurePhone/ProductKeyFeatures.md +25 -0
@@ 0,0 1,25 @@
+PurePhone product key features
+==============================
+
+- 3 modes (offline, do not disturb, connected) with magnetometer support
+- approved contacts list
+- threaded messaging with templates, drafts, UTF8 and basic emoji support
+- audio player supporting MP3, WAV, FLAC formats and indexed ID3 Tags
+- meditation app
+- calendar app
+- calculator
+- alarm clock
+- contacts and calendar synchronization via Mudita Center desktop app
+- flashlight
+- user interface optimized for E Ink displays with frontlight support
+- dark mode
+- Bluetooth headset connectivity with A2DP (Advanced Audio Distribution Profile) and HSP (Headset Profile) support
+- Passive Dual SIM support
+- USB-C Fast Charging
+- VoLTE and internet tethering support
+- HAL (Hardware Abstraction Layer) between the hardware and the OS
+- system manager that restores the system after switching on the device or performs the initial start-up
+- application manager for managing application lifecycle
+- SQLite database for storing contacts and notes
+- VFS (Virtual File System) + file storage based on `lwext4`
+- MTP (Media Transfer Protocol) support
M test/README.md => test/README.md +5 -2
@@ 8,8 8,11 @@ with `service-desktop` service in the operating system and get data from the int
Both `service-desktop` and functional tests are using [`pyTest`](https://github.com/pytest-dev/pytest/) -
a testing framework written for Python.
Convenient usage of pre-defined fixtures and `harness` API enables quick development of further tests.
-## Update utility
-To be able to flash release package without Mudita Center app or entering the bootloader you can use the script provided in `firmware_utility_test` folder. [Here](firmware_update_test/README.md) is a short guide how to use it.
+
+# Please note that
+* active development of test harness is kept here: [MuditaOSHarness](https://github.com/mudita/QAMuditaHarness)
+* active tests development is kept here: [QAMuditaOS](https://github.com/mudita/QAMuditaHarness)
+
## Test harness API
As a part of the test bundle, test harness is responsible for low-level communication with target or linux simulator.
As for now, it consists of the following methods that can be used during writing tests: