docs/TargetMaintenance/CreatingAUnifiedTarget.md

   1 # How to Create a Unified Target Configuration
   2
   3 ## 1. Considerations for Unified Target Configurations
   4
   5 ### 1.1. General
   6
   7 Unified Target Configurations are very flexible - anything that can be configured in Betaflight can be added to a Unified Target Configuration. This is intentional, as it allows Unified Target Configurations to be adapted to many different kinds of targets, from 'general purpose' flight controller boards over 'all in one' boards with on-board ESC and RX all the way to targets for 'ready to fly' craft that come pre-configured and pre-tuned.
   8
   9 However, this flexibility also puts the onus on target designers to be reasonable about what they add to the Unified Target Configurations that they create and propose for publication. In general, Betaflight tries to minimise the risk of damage or injury to users, and to avoid configurations that will create problems and potential support issues for a majority of users of a particular target. We reserve the right to refuse to add Unified Target Configurations that are in breach of these principles. Furthermore, target creators are advised to use common sense, and refrain from using configuration that is likely to annoy most users of their hardware - users are not likely to consider products from a manufacturer that has annoyed them in the past for future purchases.
  10
  11 Another expectation is that Unified Target Configurations that are submitted for publication are **tested** - please, in the interest of your customers, do not submit untested configurations. Instructions on how to install Betaflight with a new and unpublished Unified Target Configuration can be found [here](https://youtu.be/gO7HyoXYYLY).
  12
  13
  14 ### 1.2. Minimum configuration
  15
  16 The expectation is that a Unified Target Configuration contains at least all of the settings to make the hardware on a board work for the user out of the box. The instructions in 2. can be used to create such a configuration from a legacy target. For any hardware that is not configured to work in the Unified Target Configuration, Betaflight's answer to support requests for this hardware will be 'target X does not support this hardware'.
  17
  18
  19 ### 1.3. Don'ts
  20
  21 These are things that will result in a Unified Target Configuration being rejected by Betaflight, such as:
  22 - any settings that are equal to the defaults in the firmware (e.g. `resource ... NONE`). Having such settings included results in targets that are more likely to break with new versions of the firmware, and are therefore harder to maintain and more likely to cause support issues;
  23 - pre-setting any calibration settings that are dependent on and different for every board, like `acc_calibration` - these are designed for the user to be prompted to calibrate them when connecting to Betaflight Configurator, in order to get the correct calibration for their hardware;
  24 - Unified Target Configurations that result in safety issues or a setup that is potentially illegal to be used where the user is, such as:
  25   - setting `motor_pwm_protocol` to any digital protocol - if this default configuration is used with ESCs that do not support digital protocols, it is likely to result in motors spinning up as soon as a battery is connected. The default of `DISABLED` is safe, and the user will be asked to select a motor protocol that is appropriate for their ESCs when they connect to Betaflight Configurator. (Exception: If a Unified Target Configuration is to be used for an all-in-one / RTF product only, an appropriate value for `motor_pwm_protocol` for the on-board ESCs can be selected.)
  26   - pre-setting any VTX table settings - allowable values for these are governed by law in most countries, and it is up to the manufacturer / supplier of the VTX hardware and the user to make sure that they are complying with the laws in their country.
  27 - setting any values that default to auto-detection (like `baro_hardware`, `mag_hardware`) to `NONE` - the default of `AUTO` is designed to work with no hardware present, and setting the value to `NONE` will result in support issues from users wanting to add their own hardware. (Exception: Boards that do not have any pins or pads for an SPI or I2C bus exposed _can_ define these settings as `NONE`.)
  28 - pre-setting tuning settings for general purpose boards. Betaflight puts a lot of effort into shipping firmware with a default tune that is designed to work reliably across a wide range of hardware, and is extensively tested before every release. All of our documentation is based on this default tune. Adding a different tune to a Unified Target Configuration will result in additional support issues from users for whom the instructions provided by Betaflight do not work. Furthermore, these custom defaults are likely to become outdated with future releases of Betaflight. (Exception: For Unified Target Configurations that are used with only one RTF offering with fixed hardware, it may make sense to add a tune that is optimised for the hardware.)
  29
  30
  31 ### 1.4 Discouraged
  32
  33 Betaflight advises target creators against adding any setting to their Unified Target Configuration if it is not strictly related hardware configuration. Examples for discouraged settings are:
  34 - OSD element configuration;
  35 - craft name;
  36 - rates
  37
  38 All of these are really user preferences, and adding them as part of a Unified Target Configuration just means that most customers of this hardware will have to spend extra time on reverting the presets before they can set up their own preferences. There are no strict rules here, and what is reasonable will be dependent on what type of target it is, but manufacturers are advised to use common sense.
  39
  40
  41 ## 2. Creating a Unified Target Configuration
  42
  43 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.
  44
  45 ### 2.1. Flash the firmware onto your board
  46
  47 (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.)
  48
  49 - the important part is that this is the firmware for the target you want to convert to a Unified Target configuration;
  50
  51 - make sure to enable 'Full chip erase' before flashing, or reset to default with `defaults` in CLI;
  52
  53 - 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 `#`.
  54
  55
  56 ### 2.2. Get a dump of your board configuration
  57
  58 - re-start CLI (Disconnect / Connect), then do a `dump hardware`, save the output into a file with 'Save to File'.
  59
  60
  61 ### 2.3. Add the board and manufacturer information
  62
  63 - edit the file from the previous step, 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](https://github.com/betaflight/unified-targets/tree/master/Manufacturers.md);
  64 - if the manufacturer is not listed, open an [issue](https://github.com/betaflight/betaflight/issues) and ask for a new id to be assigned. This issue needs to contain the following: name of the company selling the board and supporting customers of it; a website URL for this company. In a future release of the Betaflight configurator, the listing for every board will include this company name, and users will be able to open the company's website from within Betaflight configurator. Allow for a day or two for the Betaflight team to respond to your issue and assign a manufacturer it;
  65 - for boards that are homebrew and / or not planned for commercial availability, use `CUST` as the `manufacturer_id`.
  66
  67
  68 ### 2.4. Flash the Unified Target firmware
  69
  70 - 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.
  71
  72 |Unified Target|MCU Type|
  73 |-|-|
  74 |STM32F405|STM32F405|
  75 |STM32F411|STM32F411|
  76 |STM32F7X2|STM32F722|
  77 |STM32F745|STM32F745|
  78
  79 - 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.
  80
  81
  82 ### 2.5. Do the initial setup for your Unified Target configuration
  83
  84 - connect to your board running the Unified Target firmware, enter CLI;
  85
  86 - copy / paste the contents of the dump created in 2. into CLI, then enter `save`;
  87
  88 - when the board reboots now, the LEDs should start working again - this is a sign that the previous step was successful.
  89
  90
  91 ### 2.6. Add custom settings for your board to the Unified Target configuration
  92
  93 - enter the command: `feature OSD` in CLI, just before the #master section (to switch on OSD by default);
  94
  95 - the following steps are optional (omitting it will give users of your board a minimal but working board configuration when using a Unified Target):;
  96
  97         - 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;
  98
  99         - 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;
 100
 101 - save the changes;
 102
 103
 104 ### 2.7. Create a Unified Target configuration file for your board
 105
 106 - re-start CLI (Disconnect / Connect), then do a `diff all bare`, save the output into a file named `<manufacturer_id>-<board_name>.config` with 'Save to File'. It is crucial that the name exactly matches the manufacturer id and board name specified in the file, or else checking of the pull request you are going to open in a subsequent step will fail;
 107
 108 - edit the resulting file and identify the first line in the file starting with `# Betaflight`. This line (called the banner line) should be left untouched, and it has to be the first line in the file. Whatever content is found above this line,  delete it. Likewise, there must be no extra lines after the last line starting with `set` - delete all subsequnet lines otherwise;
 109
 110 ### 2.8. Test
 111
 112 - thoroughly test your new Unified Target configuration with the actual hardware (or a prototype of it). Make sure you test all peripherals (gyro, OSD, flash, SDcard, ...) and all motor outputs (with analog and digital protocols). Ideally you want to flight test as well. Remember that Betaflight does no testing of your Unified Target configuration, and once it has been accepted it will become available to your customers through Betaflight Configurator immediately - if it does not work then this will reflect badly onto your company and its products;
 113
 114 ### 2.9. Get it added to Betaflight
 115 - open a [pull request](https://github.com/betaflight/unified-targets/pulls) to put your target configuration into `configs/default`.