diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 27ac1c71f..005f4e942 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,3 +1,22 @@ +## Important: New requirements for the submission of new targets + +As announced earlier in https://github.com/betaflight/betaflight#betaflight-40, Betaflight 4.0 is introducing a radically new way to define targets, the so-called 'Unified Targets'. + +This new approach makes it possible to use the same firmware binary (the so called 'Unified Target firmware') for all boards that share the same MCU type (only supported on F4 and F7). Manufacturers will be able to add support for new boards by simply publishing a new configuration (the so called 'Unified Target configuration') for their new board. Users can then simply load the already published Unified Target firmware and the new Unified Target configuration onto their new board to get it to work. + +Work to give users a simple way to flash unified targets in Betaflight configurator still needs to be done, so Betaflight 4.0 will be released with targets done in the 'legacy' way. But the plan is to add support for seamless use of Unified Targets into Betaflight configurator after Betaflight 4.0 has been released, and convert all of the existing F4 and F7 targets to the new format before the release of Betaflight 4.1. + +In order to be prepared for this move, the following new requirements for pull requests adding new targets or modifying existing targets are put in place from now on: + +1. After the release of Betaflight 4.0.0, new F3 based targets can only be added into the `4.0.x-maintenance` branch. This ties in with the release of firmware for F3 based targets ending after 4.0: https://github.com/betaflight/betaflight#end-of-active-development-for-stm32f3-based-flight-controllers; + +All subsequent rules exclude F3 based targets: + +2. For any new target that is to be added, both a 'legacy' format target definition into `src/main/target/` and a new Unified Target config into `unified_targets/configs/` need to be submitted. See the for how to create a Unified Target configuration: https://github.com/betaflight/betaflight/blob/master/unified_targets/docs/CreatingAUnifiedTarget.md; + +3. For changes to existing targets, the change needs to be applied to both the 'legacy' format target definition in `src/main/target/` and a new Unified Target config in `unified_targets/configs/`. If no Unified Target configuration for the target exists, a new Unified Target configuration will have to be created and submitted alongside the proposed change. + + ## Important: Feature freeze / release candidate phase for Betaflight 4.0 From 01 Mar 2019 until the release of Betaflight 4.0.0 (scheduled for 01 Apr 2019), the project is in a 'feature freeze / release candidate' phase. This means: @@ -9,19 +28,6 @@ From 01 Mar 2019 until the release of Betaflight 4.0.0 (scheduled for 01 Apr 201 3. All other pull requests will be scheduled for 4.1, and discussed / reviewed / merged into `master` after 4.0.0 has been released. Please keep in mind that this potentially means that you will have to rebase your changes if they are broken by bugfixes made for 4.0. -## Important: Embargo on new targets for Betaflight 4.0 - -As announced earlier in https://github.com/betaflight/betaflight#betaflight-40, Betaflight 4.0 will introduce a radically new way to define targets. At the moment, we are making the changes necessary for this, and this requires some changes to how targets are defined in the 'legacy' way. Because of this, any pull request opened against `master` that introduces a new target is likely to be outdated by the time it has been reviewed. This means extra work for the target maintainer and the reviewers, for little or no benefit. - -Because of this, the following embargo is put in place: - -1. From 30/12/2018 on until the release of Betaflight 4.0 (scheduled for 01/04/2019), no pull requests that introduce new targets against `master` are accepted. Because any such pull requests will be outdated by the time 4.0 is released, they will be closed; - -2. During the time that 1. is in place, pull requests adding new targets (in 3.5 format) against the `3.5.x-maintenance` branch will be considered. This is an exception to the rule that all pull requests must be opened against `master`. This exception only applies to pull requests containing no other changes than a new target and a documentation page for the new target. These new targets will be included in upcoming 3.5 maintenance releases; - -3. Targets added under the exception in 2. will have to be ported into 4.0 before 4.0 is released. The format that these targets will have in 4.0 is yet to be determined, and instructions for porting the targets will have to be written, but we expect the maintainers of these targets to make themselves available to assist with this task when the time comes. Please follow the news and updates that are posted to https://betaflight.com/ or the Betaflight GitHub page (https://github.com/betaflight/betaflight) to keep track of when action is required. - - ## Important considerations when opening a pull request: 1. Pull requests will only be accepted if they are opened against the `master` branch. Pull requests opened against other branches without prior consent from the maintainers will be closed; diff --git a/README.md b/README.md index 19c664bf2..1ab32e392 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,25 @@ This fork differs from Baseflight and Cleanflight in that it focuses on flight p ## News +### New requirements for the submission of new targets + +As [announced earlier](https://github.com/betaflight/betaflight#betaflight-40), Betaflight 4.0 is introducing a radically new way to define targets, the so-called 'Unified Targets'. + +This new approach makes it possible to use the same firmware binary (the so called 'Unified Target firmware') for all boards that share the same MCU type (only supported on F4 and F7). Manufacturers will be able to add support for new boards by simply publishing a new configuration (the so called 'Unified Target configuration') for their new board. Users can then simply load the already published Unified Target firmware and the new Unified Target configuration onto their new board to get it to work. + +Work to give users a simple way to flash unified targets in Betaflight configurator still needs to be done, so Betaflight 4.0 will be released with targets done in the 'legacy' way. But the plan is to add support for seamless use of Unified Targets into Betaflight configurator after Betaflight 4.0 has been released, and convert all of the existing F4 and F7 targets to the new format before the release of Betaflight 4.1. + +In order to be prepared for this move, the following new requirements for pull requests adding new targets or modifying existing targets are put in place from now on: + +1. After the release of Betaflight 4.0.0, new F3 based targets can only be added into the `4.0.x-maintenance` branch. This ties in with the release of firmware for F3 based targets [ending after 4.0](https://github.com/betaflight/betaflight#end-of-active-development-for-stm32f3-based-flight-controllers); + +All subsequent rules exclude F3 based targets: + +2. For any new target that is to be added, both a 'legacy' format target definition into `src/main/target/` and a new Unified Target config into `unified_targets/configs/` need to be submitted. See the [instructions](https://github.com/betaflight/betaflight/blob/master/unified_targets/docs/CreatingAUnifiedTarget.md) for how to create a Unified Target configuration; + +3. For changes to existing targets, the change needs to be applied to both the 'legacy' format target definition in `src/main/target/` and a new Unified Target config in `unified_targets/configs/`. If no Unified Target configuration for the target exists, a new Unified Target configuration will have to be created and submitted alongside the proposed change. + + ### End of active development for STM32F3 based flight controllers For a while now, development of Betaflight for flight controllers based on the STM32F3 chip has been hampered by a severe limitation that this chip has: Unlike the STM32F4 and STM32F7 models, the STM32F3 versions that are used on flight controllers have only a very limited amount of flash space available to fit the firmware into. This has meant that, starting from around version 3.3, the majority of the new features that were developed for Betaflight could not be added to STM32F3 based boards. Even worse, due to improvement in basic features, other more and more of the less commonly used features had to be removed from these flight controllers, and a number of them are at a point where they only support the bare minimum of functionality required to make them fly. diff --git a/unified_targets/docs/CreatingAUnifiedTarget.md b/unified_targets/docs/CreatingAUnifiedTarget.md new file mode 100644 index 000000000..35f06a28c --- /dev/null +++ b/unified_targets/docs/CreatingAUnifiedTarget.md @@ -0,0 +1,63 @@ +# How to Create a Unified Target Configuration + +These instructions explain how to create a Unified Target configuration for an existing Betaflight target, starting out with the latest (4.0 or newer) firmware built for this target. + + +## 1. Flash the firmware onto your board + +(Theoretically there is no need for the board to match the firmware that is flashed in this step, but there is a chance that the board configuration is setting an input pin on the board to be an output pin, thus leading to a short and potential hardware damage.) + +- the important part is that this is the firmware for the target you want to convert to a Unified Target configuration; + +- make sure to enable 'Full chip erase' before flashing, or reset to default with `defaults` in CLI; + +- verify that your board is properly reset to defaults: The output of a `diff hardware` in CLI should show `board_name`, `manufacturer_id`, and lines starting with a `#`. + + +## 2. Get a dump of your board configuration + +- re-start CLI (Disconnect / Connect), then do a `dump hardware`, save the output into a file with 'Save to File'; + +- edit the resulting file and verify that `board_name` is set to the target name, and `manufacturer_id` is set to the manufacturer's id as listed in [this document](Manufacturers.md). If the manufacturer is not listed, open an [issue](https://github.com/betaflight/betaflight/issues) and ask for a new id to be assigned. For boards that are homebrew and / or not planned for commercial availability, use `CUST` as the `manufacturer_id`. + +## 3. Flash the Unified Target firmware + +- find the correct Unified Target for your board based on the MCU type, according to the table below. If your target's MCU is not listed, please open an [issue](https://github.com/betaflight/betaflight/issues) about this to let us know there is demand. Currently, MCU types with only one or two boards using them are not released as unified targets. + +|Unified Target|MCU Type| +|-|-| +|STM32F405|STM32F405| +|STM32F411|STM32F411| +|STM32F7X2|STM32F722| +|STM32F745|STM32F745| + +- find and install the firmware (4.0 or newer) for the Unified Target identified above. The firmware is available from the board type drop-down in configurator. Be aware that after flashing this firmware, the LEDs on your board will not be working - this is normal. + + +## 4. Do the initial setup for your Unified Target configuration + +- connect to your board running the Unified Target firmware, enter CLI; + +- copy / paste the contents of the dump created in 2. into CLI, then enter `save`; + +- when the board reboots now, the LEDs should start working again - this is a sign that the previous step was successful. + + +## 5. Add custom settings for your board to the Unified Target configuration + +- this step is optional. Omitting it will give users of your board a minimal but working board configuration when using a Unified Target; + +- set all the custom settings that are specific to your board (e.g. presets for serial RX on a specific port if the board's instructions are for users to use this port for the serial RX). Changes can be done in the UI or in CLI; + +- try to only include extra settings if you are certain that most / all of your users will want them - unwanted extra changes just make it harder for your users to use your board; + +- save the changes; + + +## 6. Create a Unified Target configuration file for your board + +- re-start CLI (Disconnect / Connect), then do a `diff all bare`, save the output into a file named `.config` with 'Save to File'; + +- edit the resulting file and verify that there are no extra lines before the one starting with `# Betaflight`, and no extra lines after the last line starting with `set`; + +- open a [pull request](https://github.com/betaflight/betaflight/pulls) to put your target configuration into `unified_targets/configs`. If you were assigned a new manufacturer id, als edit `unified_targets/docs/Manufacturers.md` and add this id (the list is in alphabetical order). diff --git a/unified_targets/docs/Manufacturers.md b/unified_targets/docs/Manufacturers.md index 127f0a451..b4d608171 100644 --- a/unified_targets/docs/Manufacturers.md +++ b/unified_targets/docs/Manufacturers.md @@ -1,4 +1,7 @@ -Last updated: 17/02/2019 +# Manufacturer Ids + +This is the official list of manufacturer ids (`manufacturer_id` in the target config) that will be supported for loading onto unified targets by Betaflight configurator. + |Manufacturer Id|Name|Contact| |-|-|-| @@ -13,6 +16,3 @@ Last updated: 17/02/2019 |HBRO|Holybro|http://www.holybro.com/index.html| |MTKS|Matek Systems|http://www.mateksys.com/| |RCTI|RCTimer|http://rctimer.com/| - - -This is the official list of manufacturer ids (`manufacturer_id` in the target config) that will be supported for loading onto unified targets by Betaflight configurator.