Building-custom-firmware.md

   1 # Rationale
   2
   3 Prebuilt targets may not include the (sensor) hardware you wish to use. If the hardware is already supported in iNav, it is relatively simple to build your own custom firmware.
   4
   5 For F1 targets (NAZE and friends) we are at the limit of what can be supported with the flash space available. If you want to fly F1 on anything but a very standard and limited set of hardware, it is already necessary to build custom firmware, sometimes for something as simple as a different baro sensor.
   6
   7 This guide attempts to explain the steps necessary to make simple, configuration based changes in order to generate custom firmware. It is **not** a detailed development guide.
   8
   9 # Prerequisite
  10
  11 You need a working development environment. There is [build environment documentation](https://github.com/iNavFlight/inav/tree/master/docs/development) for the major platforms (Linux, MacOS, Windows). This documentation tends to quickly become obsolete as compiler versions evolve (as will this page:). In particular, using contemporary compiler version (e.g. as of June 2017, `arm-none-eabi-gcc` 6.3.\*) is recommended, as a contemporary compiler  will most likely match that being used by iNav developers. For example, the [Building in Ubuntu](https://github.com/iNavFlight/inav/blob/master/docs/development/Building%20in%20Ubuntu.md) document is completely out of date; a modern Linux distribution (Ubuntu or Fedora current release) will provide a contemporary (good) compiler without having to use 3rd party repositories. Arch Linux may provide the opposite problem, its (June 2017) offering `arm-none-eabi-gcc` 7.1.\* creates larger hex files than the 6.3 series, and downgrading may be recommended. If in doubt, please ask on the [RC Groups thread](https://www.rcgroups.com/forums/showthread.php?2495732-Cleanflight-iNav-%28navigation-rewrite%29-project) for advice.
  12
  13 Note that the above version numbers are going to be completely obsolete as you read this article.
  14
  15 ## Virtual Machine Environment
  16
  17 A step by step guide to creating a virtual machine as an Inav build environment is described in the wiki  [[Making a new Virtualbox to make your own INAV]]. While the instructions are slanted towards Windows and Virtualbox, they are applicable to any OS and virtualisation engine.
  18
  19 # Target Specific Files
  20
  21 ## Overview
  22
  23 For basic configuration changes, the files are found under `src/main/targets`. At the top level this includes a separate directory for each target:
  24 ```
  25 src/main/target
  26 ├── AIRBOTF4
  27 ├── AIRHEROF3
  28 ├── ALIENFLIGHTF3
  29 ├── ALIENFLIGHTF4
  30 ├── ANYFC
  31 ├── ANYFCF7
  32 ├── ANYFCM7
  33 ├── BEEROTORF4
  34 ├── BLUEJAYF4
  35 ├── CC3D
  36 ├── CHEBUZZF3
  37 ├── CJMCU
  38 ├── COLIBRI
  39 ├── COLIBRI_RACE
  40 ├── common.h
  41 ├── CRAZEPONYMINI
  42 ├── EUSTM32F103RC
  43 ├── F4BY
  44 ├── FALCORE
  45 ├── FISHDRONEF4
  46 ├── FURYF3
  47 ├── KFC32F3_INAV
  48 ├── KROOZX
  49 ├── link
  50 ├── LUX_RACE
  51 ├── MOTOLAB
  52 ├── NAZE
  53 ├── OLIMEXINO
  54 ├── OMNIBUS
  55 ├── OMNIBUSF4
  56 ├── PIKOBLX_limited
  57 ├── PIXRACER
  58 ├── PORT103R
  59 ├── RCEXPLORERF3
  60 ├── REVO
  61 ├── RMDO
  62 ├── SPARKY
  63 ├── SPARKY2
  64 ├── SPRACINGF3
  65 ├── SPRACINGF3EVO
  66 ├── SPRACINGF3MINI
  67 ├── STM32F3DISCOVERY
  68 ├── stm32f7xx_hal_conf.h
  69 ├── system_stm32f30x.c
  70 ├── system_stm32f30x.h
  71 ├── system_stm32f4xx.c
  72 ├── system_stm32f4xx.h
  73 ├── system_stm32f7xx.c
  74 ├── system_stm32f7xx.h
  75 └── YUPIF4
  76 ````
  77 Under each target, there will be at least the files we are interested in:
  78 * `target.h` : Defines the supported hardware on this target; and
  79 * `target.mk` : Defines the source files we need to build that target.
  80
  81 e.g. in the NAZE target specific directory:
  82
  83 ```
  84 ├── NAZE
  85 │   ├── AIRHERO32.mk
  86 │   ├── hardware_revision.c
  87 │   ├── hardware_revision.h
  88 │   ├── target.c
  89 │   ├── target.h
  90 │   └── target.mk
  91
  92 ```
  93
  94
  95 ## Worked Example
  96
  97 This example will consider enabling the BMP085 / BMP180 barometer on the NAZE (for example to use a GY-652 [BMP180 / HMC5983] I2C baro and compass module on an acro Naze or Flip32).
  98
  99 ### Use a separate branch
 100
 101 ```
 102 $ git checkout -b my_super_special_branch
 103 ```
 104
 105 This will isolate your work from the base repo and allow making a pull request if you decide to contribute your changes back to the project.
 106
 107 ### target.h
 108
 109 If we examine `src/main/target/NAZE/target.h` we see there are two barometers defined:
 110 ````
 111 #define BARO
 112 #define USE_BARO_MS5611 // needed for Flip32 board
 113 #define USE_BARO_BMP280
 114 ````
 115 So we can remove one (or both) of these and instead define the use of BMP085 (BMP085 and BMP180 use the same software driver). So even this is not so easy, as you need to know that fact as well. Edit `src/main/target/NAZE/target.h` so the baro definition looks like:
 116
 117 ````
 118 #define BARO
 119 //#define USE_BARO_MS5611 // needed for Flip32 board
 120 #define USE_BARO_BMP085
 121 ````
 122 Here, the MS5611 is removed (commented out with a double slash), and the BMP280 line is changed to use BMP085. One way to verify names can be to look in other, more well equipped targets; the SPRACINGF3 is sometimes a good place to look, so from `src/main/target/SPRACINGF3/target.h` we can see:
 123 ````
 124 #define BARO
 125 #define USE_BARO_MS5611
 126 #define USE_BARO_BMP085
 127 #define USE_BARO_BMP280
 128 ````
 129 ### target.mk
 130
 131 We're not done yet; we need to edit `target.mk` to tell the compiler which files we need for our bespoke sensor selection. If we look in the `src/main/target/NAZE/target.mk` file we see:
 132 ````
 133 TARGET_SRC = \
 134             drivers/accgyro/accgyro_mpu.c \
 135             drivers/accgyro/accgyro_mpu6050.c \
 136             drivers/accgyro/accgyro_mpu6500.c \
 137             drivers/accgyro/accgyro_spi_mpu6500.c \
 138             drivers/barometer/barometer_bmp280.c \
 139             drivers/barometer/barometer_ms56xx.c \
 140             drivers/compass/compass_hmc5883l.c \
 141             drivers/flash_m25p16.c \
 142             drivers/light_ws2811strip.c \
 143             drivers/light_ws2811strip_stdperiph.c \
 144             io/flashfs.c \
 145             hardware_revision.c
 146 ````
 147 So we're going to have to replace the barometer source file path; we can either root around the source tree or more easily, just look in some place that we know must use it, like `src/main/target/SPRACINGF3/target.mk` were we see:
 148 ````
 149 TARGET_SRC = \
 150             drivers/accgyro/accgyro_mpu.c \
 151             drivers/accgyro/accgyro_mpu6050.c \
 152             drivers/barometer/barometer_bmp085.c \
 153             drivers/barometer/barometer_bmp280.c \
 154             drivers/barometer/barometer_ms56xx.c \
 155             /* and more */
 156 ````
 157 So update the relevent part of `src/main/target/NAZE/target.mk`:
 158 ````
 159 TARGET_SRC = \
 160             drivers/accgyro/accgyro_mpu.c \
 161             drivers/accgyro/accgyro_mpu6050.c \
 162             drivers/accgyro/accgyro_mpu6500.c \
 163             drivers/accgyro/accgyro_spi_mpu6500.c \
 164             drivers/barometer/barometer_bmp085.c \
 165             drivers/compass/compass_hmc5883l.c \
 166             drivers/flash_m25p16.c \
 167             drivers/light_ws2811strip.c \
 168             drivers/light_ws2811strip_stdperiph.c \
 169             io/flashfs.c \
 170             hardware_revision.c
 171 ````
 172 Note: It was not really necessary to remove the BMP280 or MS5611 lines; as the defines were removed from `target.h` we would have effectively compiled an empty file.
 173
 174 ### Building
 175
 176 So now make the target.
 177 ````
 178 $ make TARGET=NAZE
 179 ...
 180 Linking NAZE
 181 arm-none-eabi-size ./obj/main/inav_NAZE.elf
 182    text    data     bss     dec     hex filename
 183  126840    1244   17012  145096   236c8 ./obj/main/inav_NAZE.elf
 184 arm-none-eabi-objcopy -O ihex --set-start 0x8000000 obj/main/inav_NAZE.elf obj/inav_1.7.2_NAZE.hex
 185 ````
 186 It fits in the 128K flash. Compare to a 'standard' build (MS5611/BMP280):
 187 ````
 188 arm-none-eabi-size ./obj/main/inav_NAZE.elf
 189    text    data     bss     dec     hex filename
 190  127616    1244   17036  145896   239e8 ./obj/main/inav_NAZE.elf
 191 arm-none-eabi-objcopy -O ihex --set-start 0x8000000 obj/main/inav_NAZE.elf obj/inav_1.7.2_NAZE.hex
 192 ````
 193 ## Caveats
 194
 195 This solves the original problem (how to build a NAZE target with BMP085/BMP180).
 196
 197 You can now commit the changes to your branch, otherwise if one wants to update the source tree (e.g.)
 198 ````
 199 git pull
 200 ````
 201 git will complain that there are uncommitted changes and won't perform the update. There are a number of solutions, some beyond the scope of this simple guide, however the easiest are:
 202
 203 * Commit to your private branch as above; or
 204 * `$ git reset --hard` before pulling ; or
 205 * Stash away the original files and restore them after pulling.
 206