users/wanleg/readme.md

   1 # Contents
   2   * [Git Basics](#git-basics)
   3        * [Update a Feature Branch](#update-a-development-branch)
   4        * [Delete Branch Locally and Remotely](#delete-branch-locally-and-remotely)
   5        * [Merge TEST branch into DEV branch](#merge-test-branch-into-dev-branch)
   6   * [STM32F103C8T6 Setup](#STM32F103C8T6-setup)
   7        * [Bootloader](#bootloader)
   8        * [Flashing QMK](#flashing-qmk)
   9
  10 ---
  11 ## Git Basics
  12 ### Update a Development Branch
  13
  14 This is how to update a working branch with upstream changes.
  15 First we'll update your local master branch. Go to your local project and check out the branch you want to merge into (your local master branch)
  16 ```bash
  17 $ git checkout master
  18 ```
  19
  20 Fetch the remote, bringing the branches and their commits from the remote repository.
  21 You can use the -p, --prune option to delete any remote-tracking references that no longer exist in the remote. Commits to master will be stored in a local branch, remotes/origin/master
  22 ```bash
  23 $ git fetch -p origin
  24 ```
  25
  26 Merge the changes from origin/master into your local master branch. This brings your master branch in sync with the remote repository, without losing your local changes. If your local branch didn't have any unique commits, Git will instead perform a "fast-forward".
  27 ```bash
  28 $ git merge origin/master
  29 ```
  30
  31 Checkout the branch you want to merge into
  32 ```bash
  33 $ git checkout <feature-branch>
  34 ```
  35
  36 Merge your (now updated) master branch into your feature branch to update it with the latest changes from your team.
  37 ```bash
  38 $ git merge master
  39 ```
  40
  41 This will open your git-configured text editor. Edit the message as desired, save, and exit the editor.
  42
  43 The above steps only update your local feature branch. To update it on GitHub, push your changes.
  44 ```bash
  45 $ git push origin <feature-branch>
  46 ```
  47
  48 ### Delete Branch Locally and Remotely
  49
  50 Executive Summary
  51 ```bash
  52 $ git push --delete <remote_name> <branch_name>
  53 $ git branch -d <branch_name>
  54 ```
  55 Note that in most cases the remote name is origin.
  56
  57 Delete Local Branch
  58 To delete the local branch use one of the following:
  59 ```bash
  60 $ git branch -d branch_name
  61 $ git branch -D branch_name
  62 ```
  63 Note: The -d option is an alias for --delete, which only deletes the branch if it has already been fully merged in its upstream branch. You could also use -D, which is an alias for --delete --force, which deletes the branch "irrespective of its merged status." [Source: man git-branch]
  64
  65 Delete Remote Branch [Updated on 8-Sep-2017]
  66 As of Git v1.7.0, you can delete a remote branch using
  67 ```bash
  68 $ git push <remote_name> --delete <branch_name>
  69 ```
  70 which might be easier to remember than
  71 ```bash
  72 $ git push <remote_name> :<branch_name>
  73 ```
  74 which was added in Git v1.5.0 "to delete a remote branch or a tag."
  75
  76 Starting on Git v2.8.0 you can also use `git push` with the `-d` option as an alias for `--delete`.
  77
  78 Therefore, the version of Git you have installed will dictate whether you need to use the easier or harder syntax.
  79
  80 ### Merge TEST branch into DEV branch
  81
  82 Executive Summary
  83 ```bash
  84 $ git checkout DEV
  85 $ git merge TEST
  86 $ git push <remote_name> DEV
  87 $ git branch -d TEST
  88 $ git push <remote_name> :TEST
  89 ```
  90 Note that in most cases the remote name is origin.
  91 The above code will merge, push to remote, and delete both the local and remote TEST branches
  92
  93 ---
  94 ## STM32F103C8T6 Setup
  95 Cheap "Blue/Black Pills" typically do not come with a bootloader installed. The Black Pill uses [generic_boot20_pb12.bin](https://github.com/rogerclarkmelbourne/STM32duino-bootloader/blob/master/binaries/generic_boot20_pb12.bin). The Blue Pill uses [generic_boot20_pc13.bin](https://github.com/rogerclarkmelbourne/STM32duino-bootloader/blob/master/binaries/generic_boot20_pc13.bin).
  96 The following instructions have been adapted from [here](http://wiki.stm32duino.com/index.php?title=Burning_the_bootloader).
  97 ### Bootloader
  98 Flashing a bootloader on to a Black Pill can be done via a USB to Serial converter (e.g. CP2102). This process should be roughly the same for all F103 boards.
  99
 100 1. Download the correct bootloader binary
 101 2. Set the 'boot 0' pin/jumper high, and 'boot 1' low
 102   B0+ to center pin
 103   B1- to center pin
 104 3. Connect the board to the PC using a USB to serial converter
 105   RX to PA9
 106   TX to PA10
 107   GND to Ground
 108   3.3V to 3.3 Volts
 109 4. Download and install __Flash Loader Demonstrator__ from [here](http://www.st.com/content/st_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-programmers/flasher-stm32.html)
 110 5. Use __Flash Loader Demonstrator__ to flash the bootloader
 111   Ensure the correct COM port is selected. Leave other options with their default values/selections.
 112   Use the "Download to Device" option, with "Erase necessary pages" selected
 113 6. After a successful flash, set 'boot 0' pin/jumper low
 114   B0- to center pin
 115   B1- to center pin (no change)
 116
 117 ### Flashing QMK
 118 As of April 2019, the `:dfu-util` target doesn't work on a \*Pill. You will need to use dfu-util directly.
 119 1. Use QMK to build your `.bin`
 120 2. Run `dfu-util.exe -d 1eaf:0003 -a 2 -D YOUR_FIRMWARE.bin"`
 121   If this is the first QMK flash on the \*Pill, you will need to synchronize your Reset Button-push with starting the command. By default, the \*Pill only stays in bootloader mode for about 3 seconds before returning to normal operation.
 122
 123 See [this page](https://docs.qmk.fm/#/faq_build?id=unknown-device-for-dfu-bootloader) if Windows can't see anything to upload to.
 124
 125 ---