.github/pull_request_template.md

@@ -1,14 +1,3 @@
-## Important: Feature freeze / release candidate phase for Betaflight 3.3
-
-From 01/02/2018 until the release of Betaflight 3.3.0 (scheduled for 01/03/2018), the project is in a 'feature freeze / release candidate' phase. This means:
-
-1. Pull requests can still be submitted as normal. Comments / discussions will probably be slower than normal due to shifted priorities;
-
-2. If your pull request is a fix for an existing bug, or an update for a single target that has a low risk of side effect for other targets, it will be reviewed, and if accepted merged into `master` for the 3.3 release;
-
-3. All other pull requests will be scheduled for 3.4, and discussed / reviewed / merged into `master` after 3.3.0 has been released. Please keep in mind that this will potentially mean that you will have to rebase your changes if they are broken by bugfixes made to 3.3.
-
-
 ## 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;

.gitignore

@@ -21,7 +21,12 @@ README.pdf
 
 # artefacts of top-level Makefile
 /downloads/
-/tools/
+
+# We have tools included for optimizaing and building the 
+# neuro-flight controller we need to version control
+/tools/*
+!/tools/graph-compiling/
+
 /build/
 # local changes only
 make/local.mk
@@ -41,3 +46,9 @@ stm32.mak
 .vagrant
 ubuntu*.log
 /.vs
+
+# Auto-generated files
+gen/
+
+*.pyc
+__pycache__/

Makefile

@@ -42,7 +42,7 @@ FLASH_SIZE ?=
 # Things that need to be maintained as the source changes
 #
 
-FORKNAME      = betaflight
+FORKNAME      = neuroflight
 
 # Working directories
 ROOT            := $(patsubst %/,%,$(dir $(lastword $(MAKEFILE_LIST))))
@@ -169,6 +169,7 @@ VPATH           := $(VPATH):$(TARGET_DIR)
 
 include $(ROOT)/make/source.mk
 
+
 ###############################################################################
 # Things that might need changing to use different tools
 #
@@ -216,6 +217,7 @@ CFLAGS     += $(ARCH_FLAGS) \
               -MMD -MP \
               $(EXTRA_FLAGS)
 
+
 ASFLAGS     = $(ARCH_FLAGS) \
               -x assembler-with-cpp \
               $(addprefix -I,$(INCLUDE_DIRS)) \
@@ -242,6 +244,7 @@ endif
 # No user-serviceable parts below
 ###############################################################################
 
+
 CPPCHECK        = cppcheck $(CSOURCES) --enable=all --platform=unix64 \
                   --std=c99 --inline-suppr --quiet --force \
                   $(addprefix -I,$(INCLUDE_DIRS)) \
@@ -264,6 +267,10 @@ CLEAN_ARTIFACTS += $(TARGET_HEX)
 CLEAN_ARTIFACTS += $(TARGET_ELF) $(TARGET_OBJS) $(TARGET_MAP)
 CLEAN_ARTIFACTS += $(TARGET_LST)
 
+
+# Neuroflight specifics 
+include $(ROOT)/make/neuroflight.mk
+
 # Make sure build date and revision is updated on every incremental build
 $(OBJECT_DIR)/$(TARGET)/build/version.o : $(SRC)
 
@@ -281,9 +288,9 @@ $(TARGET_BIN): $(TARGET_ELF)
 	@echo "Creating BIN $(TARGET_BIN)" "$(STDOUT)"
 	$(V1) $(OBJCOPY) -O binary $< $@
 
-$(TARGET_ELF):  $(TARGET_OBJS)
+$(TARGET_ELF):  $(TARGET_OBJS)  
 	@echo "Linking $(TARGET)" "$(STDOUT)"
-	$(V1) $(CROSS_CC) -o $@ $^ $(LD_FLAGS)
+	$(V1) $(CROSS_CXX) -o $@ $^ $(LD_FLAGS)
 	$(V1) $(SIZE) $(TARGET_ELF)
 
 # Compile
@@ -305,6 +312,7 @@ $(OBJECT_DIR)/$(TARGET)/%.o: %.c
 	$(CROSS_CC) -c -o $@ $(CFLAGS) $(CC_DEFAULT_OPTIMISATION) $<))
 endif
 
+
 # Assemble
 $(OBJECT_DIR)/$(TARGET)/%.o: %.s
 	$(V1) mkdir -p $(dir $@)

README.md

@@ -1,123 +1,160 @@
-![BetaFlight Notice, version 3.2 will be the last version of Betaflight to support STM32F1 based flight controllers, this includes NAZE, CC3D (original) and CJMCU like flight controllers](https://raw.githubusercontent.com/wiki/betaflight/betaflight/images/betaflight/bf3_2_notice.png)
-
-![BetaFlight](https://raw.githubusercontent.com/wiki/betaflight/betaflight/images/betaflight/bf_logo.png)
-
-Betaflight is flight controller software (firmware) used to fly multi-rotor craft and fixed wing craft.
-
-This fork differs from Baseflight and Cleanflight in that it focuses on flight performance, leading-edge feature additions, and wide target support.
-
-## Events
-
-| Date  | Event |
-| - | - |
-| 01 February 2018 | Start of feature freeze / Release Candidate window for Betaflight 3.3 |
-| 01 March 2018 | Planned [release](https://github.com/betaflight/betaflight/milestone/6) date for Betaflight 3.3 |
+![Neuroflight](https://github.com/wil3/neuroflight/raw/v3.3.x-neuroflight/logo.png)
+
+## WARNING 
+This is experimental firmware, use at your own risk! This repo is intended for academic
+and research
+purposes. 
+
+There is still a significant amount of research required to validate the
+behavior of neuro-flight controllers. If the neural network is not trained properly, instabilities and unpredictable behaviors will occur.  
+
+## Neuroflight: Next Generation Flight Control Firmware
+
+Neuroflight is the first open source neuro-flight controller software (firmware) for remotely piloting multi-rotors and fixed wing aircraft. Neuroflight's primary focus is to provide optimal flight performance.  
+
+Neuroflight aims to address limitations in PID control used in Betaflight
+through the use of neural network flight control (neuro-flight control). Neuro-flight control has been actively researched for more than a decade. In contrast to traditional control algorithms, neuro-flight control has the ability to *adapt*, *plan*, and *learn*. To account for dynamic changes Betaflight has introduced gain scheduling to increase the I gain when certain conditions are met, for example low voltages or high throttle (anti-gravity). On the other hand, neuro-flight control learns the true underlying dynamics of the aircraft allowing for optimal control depending on the current aircraft state. For example neuro-flight control has the potential to learn the batteries discharge rates to dynamically adjust control signal outputs accordingly.  The goal of this work is to provide the community with a
+stable platform to innovate and advance development of neuro-flight control design for drones, and to take a step towards
+making neuro-flight controllers mainstream. For further details refer to our
+[preprint](https://wfk.io/docs/neuroflight.pdf) and please use the following BibTex
+entry to cite our work,
+```
+@article{koch2019neuroflight,
+  title={Neuroflight: Next Generation Flight Control Firmware},
+  author={Koch, William and Mancuso, Renato and Bestavros, Azer},
+  journal={arXiv preprint arXiv:1901.06553},
+  year={2019}
+}
+```
+
+## News
+
+* 2019-08-09 Thesis defended, [Flight Controller Synthesis via Deep Reinforcement Learning](http://wfk.io/docs/WilliamKochThesisFINAL.pdf)
+* 2019-08-06 Neuroflight reaches new level of performance
+  [https://www.youtube.com/watch?v=MByCyEnsYP0](https://www.youtube.com/watch?v=MByCyEnsYP0).
+* 2018-11-14 Stable flight has been achieved with Neuroflight [https://youtu.be/c3aDDPasjjQ](https://youtu.be/c3aDDPasjjQ)
 
 ## Features
 
-Betaflight has the following features:
-
-* Multi-color RGB LED strip support (each LED can be a different color using variable length WS2811 Addressable RGB strips - use for Orientation Indicators, Low Battery Warning, Flight Mode Status, Initialization Troubleshooting, etc)
-* DShot (150, 300, 600 and 1200), Multishot, and Oneshot (125 and 42) motor protocol support
-* Blackbox flight recorder logging (to onboard flash or external microSD card where equipped)
-* Support for targets that use the STM32 F7, F4, F3 and F1 processors
-* PWM, PPM, and Serial (SBus, SumH, SumD, Spektrum 1024/2048, XBus, etc) RX connection with failsafe detection
-* Multiple telemetry protocols (CSRF, FrSky, HoTT smart-port, MSP, etc)
-* RSSI via ADC - Uses ADC to read PWM RSSI signals, tested with FrSky D4R-II, X8R, X4R-SB, & XSR
-* OSD support & configuration without needing third-party OSD software/firmware/comm devices
-* OLED Displays - Display information on: Battery voltage/current/mAh, profile, rate profile, mode, version, sensors, etc
-* In-flight manual PID tuning and rate adjustment
-* Rate profiles and in-flight selection of them
-* Configurable serial ports for Serial RX, Telemetry, ESC telemetry, MSP, GPS, OSD, Sonar, etc - Use most devices on any port, softserial included
-* VTX support for Unify Pro and IRC Tramp
-* and MUCH, MUCH more.
-
-## Installation & Documentation
-
-See: https://github.com/betaflight/betaflight/wiki
-
-## IRC Support and Developers Channel
-
-There's a dedicated Slack chat channel here:
-
-http://www.betaflight.ch/
-
-Etiquette: Don't ask to ask and please wait around long enough for a reply - sometimes people are out flying, asleep or at work and can't answer immediately.
-
-## Configuration Tool
-
-To configure Betaflight you should use the Betaflight-configurator GUI tool (Windows/OSX/Linux) that can be found here:
-
-https://chrome.google.com/webstore/detail/betaflight-configurator/kdaghagfopacdngbohiknlhcocjccjao
-
-The source for it is here:
-
-https://github.com/betaflight/betaflight-configurator
-
-## Contributing
-
-Contributions are welcome and encouraged.  You can contribute in many ways:
-
-* Documentation updates and corrections.
-* How-To guides - received help? Help others!
-* Bug reporting & fixes.
-* New feature ideas & suggestions.
-
-The best place to start is the IRC channel on gitter (see above), drop in, say hi. Next place is the github issue tracker:
-
-https://github.com/betaflight/betaflight/issues
-https://github.com/betaflight/betaflight-configurator/issues
-
-Before creating new issues please check to see if there is an existing one, search first otherwise you waste peoples time when they could be coding instead!
-
-## Developers
-
-Please refer to the development section in the `docs/development` folder.
-
-TravisCI is used to run automatic builds
-
-https://travis-ci.org/betaflight/betaflight
-
-[![Build Status](https://travis-ci.org/betaflight/betaflight.svg?branch=master)](https://travis-ci.org/betaflight/betaflight)
-
-## Betaflight Releases
-
-https://github.com/betaflight/betaflight/releases
-
-## Open Source / Contributors
-
-Betaflight is software that is **open source** and is available free of charge without warranty to all users.
-
-Betaflight is forked from Cleanflight, so thanks goes to all those whom have contributed to Cleanflight and its origins.
-
-Origins for this fork (Thanks!):
-* **Alexinparis** (for MultiWii),
-* **timecop** (for Baseflight),
-* **Dominic Clifton** (for Cleanflight), and
-* **Sambas** (for the original STM32F4 port).
-
-The Betaflight Configurator is forked from Cleanflight Configurator and its origins.
+In addition to features provided by Betaflight 3.3.3,
 
-Origins for Betaflight Configurator:
-* **Dominic Clifton** (for Cleanflight configurator), and
-* **ctn** (for the original Configurator).
+* Neural network based flight control
+* Mixing replaced by neural network 
 
-Big thanks to current and past contributors:
-* Budden, Martin (martinbudden)
-* Bardwell, Joshua (joshuabardwell)
-* Blackman, Jason (blckmn)
-* ctzsnooze
-* Höglund, Anders (andershoglund)
-* Ledvina, Petr (ledvinap) - **IO code awesomeness!**
-* kc10kevin
-* Keeble, Gary (MadmanK)
-* Keller, Michael (mikeller) - **Configurator brilliance**
-* Kravcov, Albert (skaman82) - **Configurator brilliance**
-* MJ666
-* Nathan (nathantsoi)
-* ravnav
-* sambas - **bringing us the F4**
-* savaga
-* Stålheim, Anton (KiteAnton)
+## Supported Neural Network Interfaces 
+Interfaces are defined for the sensors available on hardware. As models become
+more sophisticated additional sensors will be used (e.g. ESC telemetry, voltage
+sensor, etc.)
+
+### Gyro-based Neuro-flight controller 
+Input (x) is of size 6, where x = [roll error, pitch error, yaw error, delta roll error, delta pitch error, delta yaw error]. Inputs are unbounded and in degrees/s. Output (y) of size N corresponding
+    to motor 1 ... motor N. Each output value is in range [-1, 1].
+
+## Compiling
+
+### Pre-requites 
+
+1) **Build Model** Use [GymFC](https://github.com/wil3/gymfc) to train and create a neural network in the
+form of a Tensorflow checkpoint.  
+
+Place the generated checkpoint files (four of them: checkpoint, \*.data, \*.meta,
+\*.index-\*) in a directory which can be independently version
+controlled. 
+
+Create a file called `tf2xla.config.pbtxt` in the directory and define the
+neural network configuration according to [https://www.tensorflow.org/xla/tfcompile](https://www.tensorflow.org/xla/tfcompile).
+For example if building with OpenAI baselines PPO1 with angular rate error, and
+delta angular rate error as input , 
+```
+feed {
+    id { node_name: "pi/ob" }
+	shape { 
+		dim { size: 1}
+		dim { size: 6}
+	}
+}
+fetch {
+	id { node_name: "pi/pol/final/BiasAdd"}
+}
+
+```
+
+2) **Install Tensorflow**  Update: A patched version of Tensorflow is now
+available [here](https://github.com/wil3/tensorflow-neuroflight). If you'd like
+to patch your own copy of Tensorflow continue reading, 
+
+ Neuroflight was developed using [Tensorflow-1.8.0](https://github.com/tensorflow/tensorflow/releases/tag/v1.8.0). 
+There appears to be a bug/issue in Tensorflow-1.8.0-rc1 preventing the ABI type from being passed to tfcompile used to compile the neural network. A quick hack to force the correct ABIType is to modify compiler/xla/service/llvm_ir/llvm_util.cc. At the end of the
+function SetTargetOptions place,   
+```C++
+target_options->FloatABIType = llvm::FloatABI::Hard;
+```
+Need to investigate whether these bugs have been fixed in newer versions or
+come up with a better method to handle this. Install [Bazel](https://bazel.build/) and then build Tensorflow.
+
+There appears to be a second bug in which `tensorflow/compiler/aot/runtime.cc` does not import `malloc.h`.
+
+3) **Install Python Dependencies**
+
+Use a virtual environment to isolate Python packages. In this directory,
+
+```
+python3 -m venv env
+source env/bin/activate
+pip3 install -r requirements.txt
+```
+
+### Neuroflight compilation
+1) In `make/local.mk` define `TENSORFLOW_DIR` to the location where you have
+installed Tensorflow or alternately export this as an environment variable. 
+
+2) In `make/local.mk` define  `FC_MODEL_DIR` as the directory containing
+your neural network checkpoint.
+
+3) Refer to [Betaflight](https://github.com/betaflight/betaflight) or
+src/main/target for list of supported FCs.
+
+#### Current Tested Flight Controller Hardware
+Any F7 should be fine. Flash memory is sufficient for F4's however it is unknown how the decreased processor speed will affect
+execution of the neural network. Flight controllers known to work, 
+
+* Matek F722-STD
+
+To build firmware,
+```
+make TARGET=MATEKF722
+```
+Flash FC with `obj/neuroflight_3.3.3_MATEKF722.hex`
+
+## Configuration
+
+Neuroflight is compatible with the [Betaflight
+Configurator](https://chrome.google.com/webstore/detail/betaflight-configurator/kdaghagfopacdngbohiknlhcocjccjao)
+however any modifications to the PID controller and mixer will not do anything
+as they are not used by Neuroflight.
+
+## Development
+In order to reduce maintenance, avoid merge conflicts and keep as in sync with
+upstream Betaflight, Neuroflight's architecture will maintain a minimal footprint and
+isolate its code from Betaflight as much as possible. The following table
+describes the  files modified (M), and added (A) for Neuroflight,
+
+| Delta | File | Description |
+| --- | --- | --- |
+| M     | Makefile                  | Include neuroflight.mk |
+| A     | make/neuroflight.mk             | Specifics for compiling the neural network |
+| M     | make/source.mk            | Add new sources and Tensorflow dependencies |
+| A     | tools/graph-compiling/*    | Tools for compiling the neural network graph |
+| M     | src/main/fc/fc_core.c     | Replace PID with neuro-flight controller|
+| A     | src/main/graph/*           | Source directory supporting interface and execution of the neuro-flight controller |
+| M     | src/main/flight/mixer.*   | Inclusion of throttle mixing | 
+| A     | gen/*                | Auto-generated files to support neural network integration |
+| M     | src/main/platform.h | Remove poisoning of sprintf functions which is used deep in Tensorflow until we can find a better work around. | 
+
+
+At the time of
+development Neuroflight was forked from Betaflight 3.3.3. Since then, newer versions
+of Betaflight have increased in size as more features are packed in. Further
+testing is needed to identify if the neural network will fit in newer versions
+of the firmware. 
 
-And many many others who haven't been mentioned....