Merge branch 'develop' of JF/PineTime into master

19 files changed, 245 insertions, 17 deletions

diff --git a/doc/CompanionApps/Amazfish.md b/doc/CompanionApps/Amazfish.md
new file mode 100644
index 0000000..eb9daa0
--- /dev/null
+++ b/doc/CompanionApps/Amazfish.md
@@ -0,0 +1,15 @@
+# Amazfish
+[Amazfish](https://openrepos.net/content/piggz/amazfish) is a companion app that supports many smartwatches and activity trackers running on [SailfishOS](https://sailfishos.org/).
+
+## Features
+The following features are implemented:
+ - Scanning & detection of Pinetime-JF / InfiniTime
+ - Connection / disconnection
+ - Time synchronization
+ - Notifications
+ - Music control
+ 
+## Demo
+[This video](https://seafile.codingfield.com/f/21c5d023452740279e36/) shows how to connect to the Pinetime and control the playback of the music on the phone.
+Amazfish and Sailfish OS are running on the [Pinephone](https://www.pine64.org/pinephone/), another awesome device from Pine64.
+ 
\ No newline at end of file
diff --git a/doc/CompanionApps/Gadgetbridge.md b/doc/CompanionApps/Gadgetbridge.md
new file mode 100644
index 0000000..1a25069
--- /dev/null
+++ b/doc/CompanionApps/Gadgetbridge.md
@@ -0,0 +1,13 @@
+# Integration with Gadgetbridge
+[Gadgetbridge](https://gadgetbridge.org/) is an Android application that supports many smartwatches and fitness trackers.
+
+The integration of InfiniTime (previously Pinetime-JF) is now merged into the master branch (https://codeberg.org/Freeyourgadget/Gadgetbridge/).
+
+## Features
+The following features are implemented:
+ - Scanning & detection of Pinetime-JF / InfiniTime
+ - Connection / disconnection
+ - Notifications
+ 
+## Demo
+[This video](https://seafile.codingfield.com/f/0a2920b9d765462385e4/) shows how to scan, connect, send notification (using the debug screen) and disconnect from the Pinetime.
diff --git a/doc/CompanionApps/NrfconnectOTA.md b/doc/CompanionApps/NrfconnectOTA.md
new file mode 100644
index 0000000..0fa3cd0
--- /dev/null
+++ b/doc/CompanionApps/NrfconnectOTA.md
@@ -0,0 +1,12 @@
+# OTA using NRFConnect
+[NRFConnect](https://www.nordicsemi.com/Software-and-tools/Development-Tools/nRF-Connect-for-mobile) is a powerful application (running on Android and iOS) which allows to scan and connect to BLE devices.
+
+## Features
+ - Scanning, connect, disconnect
+ - Time synchronization
+ - OTA
+ 
+InfiniTime implements the Nordic DFU protocol for the OTA functionality. NRFConnect also supports this protocol.
+
+# Demo
+[This video](https://seafile.codingfield.com/f/a52b69683a05472a90c7/) shows how to use NRFConnect to update the firmware running on the Pinetime.
\ No newline at end of file
diff --git a/doc/CompanionApps/firmwareNoValidated.jpg b/doc/CompanionApps/firmwareNoValidated.jpg
new file mode 100644
index 0000000..28df7ea
--- /dev/null
+++ b/doc/CompanionApps/firmwareNoValidated.jpg
diff --git a/doc/CompanionApps/firmwareValidated.jpg b/doc/CompanionApps/firmwareValidated.jpg
new file mode 100644
index 0000000..0d6f99b
--- /dev/null
+++ b/doc/CompanionApps/firmwareValidated.jpg
diff --git a/doc/CompanionApps/firmwareValidationApp.jpg b/doc/CompanionApps/firmwareValidationApp.jpg
new file mode 100644
index 0000000..d78ad0c
--- /dev/null
+++ b/doc/CompanionApps/firmwareValidationApp.jpg
diff --git a/doc/SPI-LCD-driver.md b/doc/SPI-LCD-driver.md
index 3c33c25..f787aab 100644
--- a/doc/SPI-LCD-driver.md
+++ b/doc/SPI-LCD-driver.md
@@ -24,17 +24,17 @@ As I said in the introduction, the datasheet will be your bedside book during yo
 
 The schematic of your board (the Pinetime schematics in this case) will also be very important, as you'll need to know how the LCD controller is physically connected to the MCU.
 
-How to read the datasheet? I recommand to read it from the beginning to the end (no joke) at least once. You certainly do not need to read everything in details, but it's good to know what information is available and where in the document. It'll be very useful during the developpment phase.
+How to read the datasheet? I recommend to read it from the beginning to the end (no joke) at least once. You certainly do not need to read everything in details, but it's good to know what information is available and where in the document. It'll be very useful during the development phase.
 You'll want to read some part with more attention :
 - Data color coding in 4-Line Serial Interface : how to send the pixel to be display to the controller
-- Display Data Ram : how is the memory organised
+- Display Data Ram : how is the memory organized
 - Power On/Off sequence
 - System function commands : all the commands you can send to the controller.
 
 ## One Pixel at a time
 
 
-## Bulk transfert
+## Bulk transfers
 
 ## DMA
 
diff --git a/doc/bootloader/boot.png b/doc/bootloader/boot.png
new file mode 100644
index 0000000..713f715
--- /dev/null
+++ b/doc/bootloader/boot.png
diff --git a/doc/bootloader/boot.puml b/doc/bootloader/boot.puml
new file mode 100644
index 0000000..00790d7
--- /dev/null
+++ b/doc/bootloader/boot.puml
@@ -0,0 +1,19 @@
+@startuml
+
+MCU -> Bootloader: reset
+activate Bootloader
+Bootloader -> Bootloader: Recover? (no)
+Bootloader -> Bootloader: New version? (no)
+Bootloader -> Application: Jump to primary slot
+deactivate Bootloader
+
+activate Application
+note right: This is the current version of the firmware
+Application -> Application: OTA procedure
+note right: Download a new firmware version and\n store it in secondary slot
+Application -> MCU: Reset
+deactivate Application
+
+
+
+@enduml
\ No newline at end of file
diff --git a/doc/bootloader/recover.png b/doc/bootloader/recover.png
new file mode 100644
index 0000000..6c6a940
--- /dev/null
+++ b/doc/bootloader/recover.png
diff --git a/doc/bootloader/recover.puml b/doc/bootloader/recover.puml
new file mode 100644
index 0000000..3f5bafb
--- /dev/null
+++ b/doc/bootloader/recover.puml
@@ -0,0 +1,17 @@
+@startuml
+
+MCU -> Bootloader: reset
+activate Bootloader
+Bootloader -> Bootloader: Recover? (yes)
+Bootloader -> Bootloader: Restore previous firmware
+note left: Copy the previous firmware from secondary to primary slot
+Bootloader -> Application: Jump to primary slot
+deactivate Bootloader
+
+activate Application
+note right: This is the previous version\nof the firmware
+Application -> Application: Normal Operation
+Application -> MCU: Reset
+deactivate Application
+
+@enduml
\ No newline at end of file
diff --git a/doc/bootloader/upgrade.png b/doc/bootloader/upgrade.png
new file mode 100644
index 0000000..ac77d42
--- /dev/null
+++ b/doc/bootloader/upgrade.png
diff --git a/doc/bootloader/upgrade.puml b/doc/bootloader/upgrade.puml
new file mode 100644
index 0000000..c31b911
--- /dev/null
+++ b/doc/bootloader/upgrade.puml
@@ -0,0 +1,21 @@
+@startuml
+
+MCU -> Bootloader: reset
+activate Bootloader
+Bootloader -> Bootloader: Recover? (no)
+Bootloader -> Bootloader: New version? (yes)
+Bootloader -> Bootloader: Swap firmwares
+note left: Copy current firmware from primary to secondary\nand copy the new firmware from secondary to primary
+Bootloader -> Application: Jump to primary slot
+deactivate Bootloader
+
+
+activate Application
+note right: This is the new version of the firmware
+Application -> Application: Write the valid bit in flash memory
+note right: The application should provide a way to\ncheck that it is running correctly\n(selftest, user confirmation,...)\nbefore setting the valid bit.
+Application -> Application: Normal operations...
+Application -> MCU: Reset
+deactivate Application
+
+@enduml
\ No newline at end of file
diff --git a/doc/branches.md b/doc/branches.md
new file mode 100644
index 0000000..0fb8316
--- /dev/null
+++ b/doc/branches.md
@@ -0,0 +1,12 @@
+# 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:
+ - **master** : this branch is always ready to be reployed. 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.
+
+New features should be implemented in **feature branches** created from **develop**. When the feature is ready, a pull-request is created and it'll be merge into **develop** when it is succesfully reviewed and accepted.
+
+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
diff --git a/doc/buildAndProgram.md b/doc/buildAndProgram.md
index 77fee33..84d0041 100644
--- a/doc/buildAndProgram.md
+++ b/doc/buildAndProgram.md
@@ -1,19 +1,19 @@
 # Build
-##Dependencies
+## Dependencies
 To build this project, you'll need:
  - A cross-compiler : [gcc-arm-none-eabi-8-2019-q3-update](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads/8-2019q3-update)
  - The NRF52 SDK 15.3.0 : [nRF5_SDK_15.3.0_59ac345](https://developer.nordicsemi.com/nRF5_SDK/nRF5_SDK_v15.x.x/nRF5_SDK_15.3.0_59ac345.zip)
  - A reasonably recent version of CMake (I use 3.16.5)
 
-##Build steps 
-###Clone the repo
+## Build steps 
+### Clone the repo
 ```
 git clone https://github.com/JF002/Pinetime.git
 cd Pinetime
 mkdir build
 cd build
 ```
-###Project generation using CMake
+### Project generation using CMake
 CMake configures the project according to variables you specify the command line. The variables are:
 
  Variable | Description | Example|
@@ -27,22 +27,22 @@ CMake configures the project according to variables you specify the command line
 **GDB_CLIENT_TARGET_REMOTE**|Target remote connection string. Used only if `USE_GDB_CLIENT` is 1.|`-DGDB_CLIENT_TARGET_REMOTE=/dev/ttyACM0`
 
 
-####CMake command line for JLink
+#### CMake command line for JLink
 ```
 cmake -DCMAKE_BUILD_TYPE=Debug -DARM_NONE_EABI_TOOLCHAIN_PATH=... -DNRF5_SDK_PATH=... -DUSE_JLINK=1 -DNRFJPROG=... ../
 ```
 
-####CMake command line for GDB Client (Black Magic Probe)
+#### CMake command line for GDB Client (Black Magic Probe)
 ```
 cmake -DARM_NONE_EABI_TOOLCHAIN_PATH=... -DNRF5_SDK_PATH=... -DUSE_GDB_CLIENT=1 -DGDB_CLIENT_BIN_PATH=... -DGDB_CLIENT_TARGET_REMOTE=... ../
 ```
 
-####CMake command line for OpenOCD
+#### CMake command line for OpenOCD
 ```
 cmake -DARM_NONE_EABI_TOOLCHAIN_PATH=... -DNRF5_SDK_PATH=... -DUSE_OPENOCD=1 -DGDB_CLIENT_BIN_PATH=[optional] ../
 ```
 
-###Build the project
+### Build the project
 During the project generation, CMake created the following targets:
 - FLASH_ERASE : mass erase the flash memory of the NRF52.
 - FLASH_pinetime-app : flash the firmware into the NRF52.
@@ -50,7 +50,7 @@ During the project generation, CMake created the following targets:
 - pinetime-mcuboot-app : build the firmware with the support of the bootloader (based on MCUBoot).
 - pinetime-graphics : small firmware that writes the boot graphics into the SPI flash.
 
-If you just want to build the project and run it on the Pinetime, using *pinetime-app* is recommanded. See ???? for more info about bootloader support.
+If you just want to build the project and run it on the Pinetime, using *pinetime-app* is recommanded. See [this page](../bootloader/README.md) for more info about bootloader support.
 
 Build:
 ```
@@ -66,8 +66,8 @@ Binary files are generated into the folder `src`:
  - **pinetime-graphics.bin, .hex and .out** : firmware for the boot graphic in bin, hex and out formats.
  - **pinetime-graphics.map** : map file
  
-###Program and run
-####Using CMake targets
+### Program and run
+#### Using CMake targets
 These target have been configured during the project generation by CMake according to the parameters you provided to the command line.
 
 Mass erase:
@@ -80,7 +80,7 @@ Flash the application:
 make FLASH_pinetime-app
 ```
 
-###Using JLink
+### Using JLink
 Start JLinkExe:
 ```
 $ /opt/SEGGER/JLink/JLinkExe -device nrf52 -if swd -speed 4000 -autoconnect 1     
@@ -146,7 +146,7 @@ Reset: Reset device via AIRCR.SYSRESETREQ.
 J-Link>g
 ```
 
-####JLink RTT
+#### JLink RTT
 RTT is a feature from Segger's JLink devices that allows bidirectionnal communication between the debugger and the target. This feature can be used to get the logs from the embedded software on the development computer.
 
  - Program the MCU with the code (see above)
@@ -161,7 +161,7 @@ Start JLinkRTTClient
 $ JLinkRTTClient
 ```
 
-###Using GDB and Black Magic Probe (BMP)
+### Using GDB and Black Magic Probe (BMP)
 Enter the following command into GDB:
 
 ```
diff --git a/doc/buildWithDocker.md b/doc/buildWithDocker.md
new file mode 100644
index 0000000..705c6d9
--- /dev/null
+++ b/doc/buildWithDocker.md
@@ -0,0 +1,33 @@
+# Build the project using Docker
+A [Docker image (Dockerfile)](../docker) containing all the build environment is available for X86_64 and AMD64 architectures. This image makes the build of the firmware and the generation of the DFU file for OTA.
+
+## Build the image
+The image is not (yet) available on DockerHub, you need to build it yourself, which is quite easy. The following commands must be run from the root of the project.
+
+If you are running on a x86_64 computer : 
+```
+docker image build -t infinitime-build --build-arg USER_ID=$(id -u) --build-arg GROUP_ID=$(id -g) docker/x86_64/
+```
+
+And if your are running on an ARM64 device (tested on RaspberryPi4 and Pine64 PineBookPro):
+```
+docker image build -t infinitime-build --build-arg USER_ID=$(id -u) --build-arg GROUP_ID=$(id -g) docker/arm64/
+```
+
+This operation will take some time. It builds a Docker image based on Ubuntu, install some packages, download the ARM toolchain, the NRF SDK, MCUBoot and adafruit-nrfutil.
+
+When this is done, a new image named *infinitime-build* is available.
+
+## Run a container to build the project:
+
+```
+docker run --rm -v <project_root>:/sources infinitime-build
+```
+
+Replace *<project_root>* by the path of the root of the project on your computer. For example:
+
+```
+docker run --rm -v /home/jf/git/PineTime:/sources infinitime-build
+```
+
+This will start a container, build the firmware and generate the MCUBoot image and the DFU file. The output of the build is stored in **<project_root>/built/output**.
\ No newline at end of file
diff --git a/doc/contribute.md b/doc/contribute.md
new file mode 100644
index 0000000..53c6ac0
--- /dev/null
+++ b/doc/contribute.md
@@ -0,0 +1,24 @@
+# How to contribute?
+## Report bugs
+You use your Pinetime and find a bug in the firmware? [Create an issue on Github](https://github.com/JF002/Pinetime/issues) explaining the bug, how to reproduce it, the version of the firmware you use...
+## Write and improve documentation
+Documentation might be incomplete, or not clear enough, and it is always possible to improve it with better wording, pictures, photo, video,... 
+
+As the documentation is part of the source code, you can submit your improvements to the documentation by submitting a pull request (see below).
+## Fix bugs, add functionalities and improve the code
+You want to fix a bug, add a cool new functionality or improve the code? See *How to submit a pull request below*.
+## Spread the word
+Pinetime is a cool open source project that deserves to be know. Talk about it around you, on social networks, on your blog,... and let people know that we are working on an open-source firmware for a smartwatch!
+
+# How to submit a pull request ?
+Your contribution is more than welcome! 
+
+If you want to fix a bug, add a functionality or improve the code, you'll first need to create a branch from the **develop** branch (see [this page about the branching model](./branches.md)). This branch is called a feature branch, and you should choose a name that explains what you are working on (ex: "add-doc-about-contributions"). In this branch, try to focus on only one topic, bug or feature. For example, if you created this branch to work on the UI of a specific application, do not commit modifications about the SPI driver. If you want to work on multiple topics, create one branch per topic.
+
+When your feature branch is ready, make sure it actually works and do not forget to write documentation about it if necessary.
+
+Then, you can submit a pull-request for review. Try to describe your pull request as much as possible: what did you do in this branch, how does it work, how is it designed, are there any limitations,... This will help the contributors to understand and review your code easily.
+
+Other contributors can post comments about the pull request, maybe ask for more info or adjustements in the code.
+
+Once the pull request is reviewed an accepted, it'll be merge in **develop** and will be released in the next release version of the firmware.
\ No newline at end of file
diff --git a/doc/filesInReleaseNotes.md b/doc/filesInReleaseNotes.md
new file mode 100644
index 0000000..d293051
--- /dev/null
+++ b/doc/filesInReleaseNotes.md
@@ -0,0 +1,56 @@
+# Using the releases
+For each new *stable* version of Pinetime, a [release note](https://github.com/JF002/Pinetime/releases) is created. It contains a description of the main changes in the release and some files you can use to flash the firmware in your Pinetime.
+
+This page describes the files from the release notes and how to use them.
+
+**NOTE :** the files included in different could be different. This page describes the release note of [version 0.7.1](https://github.com/JF002/Pinetime/releases/tag/0.7.1), which is the version that'll probably be pre-programmed at the factory for the next batch of Pinetime devkits.
+
+## Files included in the release note
+
+### Standalone firmware
+This firmware is standalone, meaning that it does not need a bootloader to actually run. It is intended to be flash at offset 0, meaning it will erase any bootloader that might be present in memory.
+
+ - **pinetime-app.out** : Output file of GCC containing debug symbols, useful is you want to debug the firmware using GDB.
+ - **pinetime-app.hex** : Firmware in Intel HEX file format. Easier to use because it contains the offset in memory where it must be flashed, you don't need to specify it.
+ - **pintime-app.bin** : Firmware in binary format. When programming it, you have to specify the offset (0x00) in memory where it must be flashed.
+ - **pinetime-app.map** : Map file containing all the symbols, addresses in memory,...
+ 
+**This firmware must be flashed at address 0x00 in the main flash memory**
+
+### Bootloader
+The bootloader  is maintained by [lupyuen](https://github.com/lupyuen) and is a binary version of [this release](https://github.com/lupyuen/pinetime-rust-mynewt/releases/tag/v5.0.4).
+
+ - **bootloader.hex** : Firmware in Intel HEX file format.
+ 
+ **This firmware must be flashed at address 0x00 in the main flash memory**
+
+
+### Graphics firmware 
+This firmware is a small utility firmware that writes the boot graphic in the external SPI flash memory. You need it if you want to use the [bootloader](../bootloader/README.md).
+
+ - **pinetime-graphics.out** : Output file of GCC containing debug symbols, useful is you want to debug the firmware using GDB.
+ - **pinetime-graphics.hex** : Firmware in Intel HEX file format. Easier to use because it contains the offset in memory where it must be flashed, you don't need to specify it.
+ - **pintime-graphics.bin** : Firmware in binary format. When programming it, you have to specify the offset (0x00) in memory where it must be flashed.
+ - **pinetime-graphics.map** : Map file containing all the symbols, addresses in memory,...
+ 
+**This firmware must be flashed at address 0x00 in the main flash memory**
+
+### Firmware with bootloader
+This firmware is intended to be used with our [MCUBoot-based bootloader](../bootloader/README.md).
+
+ - **pinetime-mcuboot-app-image.hex** : Firmware wrapped into an MCUBoot image. This is **the** file that must be flashed **@ 0x8000** into flash memory. If the [bootloader](../bootloader/README.md) has been successfully programmed, it should run this firmware after the next reset.
+
+The following files are not directly usable by the bootloader:
+
+ - **pinetime-mcuboot-app.bin** : Output file of GCC containing debug symbols, useful is you want to debug the firmware using GDB.
+ - **pinetime-mcuboot-app.hex** : Firmware in Intel HEX file format. 
+ - **pinetime-mcuboot-app.bin** : Firmware in binary format. 
+ - **pinetime-mcuboot-app.map** : Map file containing all the symbols, addresses in memory,...
+
+### OTA (Update the firmware Over-The-Air)
+Once the bootloader and application firmware are running, it is possible to update the current firmware or even replace it with another firmware **that uses the same bootloader based on MCUBoot**.
+
+**NOTE :** Use this file **only** if you programmed our [MCUBoot-based bootloader](../bootloader/README.md). This file is not compatible with other bootloaders like the one that is based on the closed source NRF SoftDevice !
+
+ - **pinetime-app-dfu.zip** : This is the file you must provide toNRFConnect to update the firmware over BLE.
+
diff --git a/doc/versioning.md b/doc/versioning.md
new file mode 100644
index 0000000..b08af71
--- /dev/null
+++ b/doc/versioning.md
@@ -0,0 +1,6 @@
+# Versioning
+The versioning of this project is based on [Semantic versionning](https://semver.org/) :
+
+ - The **patch** is incremented when we fix a bug on a **released** version (most of the time using a **hotfix** branch).
+ - The **minor** is incremented when we release a new version with new features. It corresponds to a merge of **develop** into **master**.
+ - The **major** should be incremented when a breaking change is made to the application. We still have to define what is a breaking change in the context of this project. For now, I suggest that it stays **0** until we have a fully functionning firmware suited for the final user.
\ No newline at end of file