unified_targets/docs/CreatingAUnifiedTarget.md

   1 # How to Create a Unified Target Configuration
   2
   3 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.
   4
   5
   6 ## 1. Flash the firmware onto your board
   7
   8 (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.)
   9
  10 - the important part is that this is the firmware for the target you want to convert to a Unified Target configuration;
  11
  12 - make sure to enable 'Full chip erase' before flashing, or reset to default with `defaults` in CLI;
  13
  14 - 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 `#`.
  15
  16
  17 ## 2. Get a dump of your board configuration
  18
  19 - re-start CLI (Disconnect / Connect), then do a `dump hardware`, save the output into a file with 'Save to File';
  20
  21 - 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`.
  22
  23 ## 3. Flash the Unified Target firmware
  24
  25 - 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.
  26
  27 |Unified Target|MCU Type|
  28 |-|-|
  29 |STM32F405|STM32F405|
  30 |STM32F411|STM32F411|
  31 |STM32F7X2|STM32F722|
  32 |STM32F745|STM32F745|
  33
  34 - 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.
  35
  36
  37 ## 4. Do the initial setup for your Unified Target configuration
  38
  39 - connect to your board running the Unified Target firmware, enter CLI;
  40
  41 - copy / paste the contents of the dump created in 2. into CLI, then enter `save`;
  42
  43 - when the board reboots now, the LEDs should start working again - this is a sign that the previous step was successful.
  44
  45
  46 ## 5. Add custom settings for your board to the Unified Target configuration
  47
  48 - this step is optional. Omitting it will give users of your board a minimal but working board configuration when using a Unified Target;
  49
  50 - 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;
  51
  52 - 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;
  53
  54 - save the changes;
  55
  56
  57 ## 6. Create a Unified Target configuration file for your board
  58
  59 - re-start CLI (Disconnect / Connect), then do a `diff all bare`, save the output into a file named `<board_name>.config` with 'Save to File';
  60
  61 - 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`;
  62
  63 - 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).