# About this repo First of all, I love Ardupilot. I use it on countless projects and encourage the others to use it, explaining its functionalities and why it is simply better. But since I am often building UAVs on inexpensive hardware (such as the F405 microcontroller) which are not capable of running the full Ardupilot. Therefore, I was often using [custom.ardupilot.org](https://custom.ardupilot.org) to build the firmware I needed. Ardupilot Devs did a great job in selecting the default feature for each boards however there were times when I needed to customise the feature in a more granular way (for instance, change the only VTX font the F405 can visualise replacing font0.bin - or the VTX table that in better Flight Controllers, is handled by a LUA Script. I then decided to clone the original repository and create this application. This version differs from the original upstream ArduPilot Custom Firmware Builder by introducing a dedicated Custom Overlay Manager, and features a lightweight, sidecar web application that allows developers to easily upload, create, and manage custom C files, hardware definitions, and folder structures directly from their browser. To support this, the core firmware builder script has been modified to automatically seek out these custom files and seamlessly inject them into the cloned ArduPilot source tree right before the compilation step begins. This should allow to test and build modified firmware without ever needing to manually fork or alter the base ArduPilot repository. The techical choice of adding a sidecar container is dictated by the need to keep this code as close as possible to the official repository. This makes importing the official upstream changes into this easily. So, the only modification done to this code specifically are in the `builder.py` and `index.html` template. ### What's New in this Version This version differs from the original upstream ArduPilot Custom Firmware Builder by introducing a dedicated **Custom Overlay Manager**. **Key Enhancements:** - **Sidecar Web Application:** A lightweight interface that allows developers to easily upload, create, and manage custom C files, hardware definitions, and folder structures directly from their browser. - **Automated Source Injection:** The core firmware builder script has been modified to automatically seek out these custom files and seamlessly inject them into the cloned ArduPilot source tree right before the compilation step begins. ### How to run this code Simply clone this repository and launch the docker container as explained in the official documentation, that I have copied below this paragraph... Safe flying! ### Nginx configuration example ```text server { listen 80; listen [::]:80; server_name ardupilot.equalmass.com; rewrite ^ https://$http_host$request_uri? permanent; # force redirect http to https server_tokens off; } server { listen 443 http2; listen [::]:443 http2; ssl on; # Note: If Nginx warns about this on restart, change to 'listen 443 ssl http2;' ssl_certificate /etc/nginx/ssl/equalmass.com.cer; ssl_certificate_key /etc/nginx/ssl/equalmass.com.key; ssl_dhparam /etc/nginx/ssl/dhparam.pem; server_name ardupilot.equalmass.com; ssl_session_timeout 5m; ssl_protocols TLSv1 TLSv1.1 TLSv1.2; ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:DHE-RSA-CAMELLIA256-SHA:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-SEED-SHA:DHE-RSA-CAMELLIA128-SHA:HIGH:!aNULL:!eNULL:!LOW:!3DES:!MD5:!EXP:!PSK:!SRP:!DSS'; ssl_prefer_server_ciphers on; proxy_set_header X-Forwarded-For $remote_addr; add_header Strict-Transport-Security "max-age=31536000; includeSubDomains"; server_tokens off; # ========================================================= # NEW SIDECAR ROUTING # Intercepts traffic to /patch-manager/ and sends it to port 11081. # The trailing slash on '11081/' is crucial—it strips the prefix # so the FastAPI app receives standard routing requests. # ========================================================= location /patch-manager/ { proxy_pass http://192.168.195.4:11081/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Host $server_name; proxy_set_header X-Forwarded-Proto https; client_max_body_size 50M; # Allows uploading larger custom files } # ========================================================= # MAIN ARDUPILOT ROUTING # Handles all standard traffic and sends it to port 11080. # ========================================================= location / { proxy_pass http://192.168.195.4:11080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Host $server_name; proxy_set_header X-Forwarded-Proto https; access_log /var/log/nginx/ardupilot.access.log; error_log /var/log/nginx/ardupilot.error.log; proxy_read_timeout 1200s; client_max_body_size 0; } } ``` # Upstream Firmware Builder documentation ## Table of Contents 1. [Overview](#overview) 2. [Live Versions](#live-versions) 3. [Running Locally Using Docker](#running-locally-using-docker) 4. [Running Locally Without Docker on Ubuntu](#running-locally-without-docker-on-ubuntu) 5. [Directory Structure](#directory-structure) 6. [Acknowledgements](#acknowledgements) ## Overview The ArduPilot Custom Firmware Builder is a web-based application designed to generate downloadable customized ArduPilot firmware, tailored to user specifications. This tool facilitates the customization and building of firmware by allowing users to select the options that best fit their needs, thus providing a streamlined interface for creating ArduPilot firmware. ## Live Versions - **Stable Version:** The stable version of the ArduPilot Custom Firmware Builder can be accessed at [custom.ardupilot.org](https://custom.ardupilot.org). - **Beta Version:** We maintain a beta version available at [custom-beta.ardupilot.org](https://custom-beta.ardupilot.org) where newly developed features are tested before they are rolled out in the stable version. ## Running Locally Using Docker To minimize setup overhead and enhance ease of use, running this application in Docker containers is highly recommended. Follow the instructions below to run the application locally using Docker: 1. **Install Docker and Docker Compose:** Make sure Docker and Docker Compose are installed on your machine. For installation instructions, visit the [Docker website](https://docs.docker.com/engine/install). 2. **Clone the Repository:** ```bash git clone https://github.com/ardupilot/CustomBuild.git cd CustomBuild ``` 3. **Configure Environment Variables:** Copy the `.env` file to the root of the cloned repository from `./examples/.env.sample` and configure the necessary parameters within it. ```bash cp ./examples/.env.sample .env ``` 4. **Build and Start the Docker Containers:** - To build and start the application, run: ```bash sudo docker compose up --build ``` - If you want to run the application with the last built image, simply execute: ```bash sudo docker compose up ``` Use the `-d` flag to run the application in daemon mode: ```bash sudo docker compose up -d ``` **Note:** When starting the application for the first time, it takes some time to initialize the ArduPilot Git repositories at the backend. This process also involves populating the list of available versions and releases using the GitHub API, so please be patient. 5. **Access the Web Interface:** The application binds to port 11080 on your host machine by default. Open your web browser and go to `http://localhost:11080` to interact with the web interface. To change the port, set the `WEB_PORT` environment variable in the .env file mentioned in the _Configure Environment Variables_ section. 6. **Stopping the Application:** To stop the application, you can use the following command: ```bash sudo docker compose down ``` This will stop and remove the containers, but it will not delete any built images or volumes, preserving your data for future use. ## Running Locally Without Docker on Ubuntu To run the ArduPilot Custom Firmware Builder locally without Docker, ensure you have an environment capable of building ArduPilot. Refer to the [ArduPilot Environment Setup Guide](https://ardupilot.org/dev/docs/building-setup-linux.html) if necessary. 1. **Clone the Custom-Build Repository:** ```bash git clone https://github.com/ardupilot/CustomBuild.git cd CustomBuild ``` 2. **Create and use a virtual environment:** ```bash python3 -m venv path/to/virtual/env source path/to/virtual/env/bin/activate ``` If the python venv module is not installed, run: ```bash sudo apt install python3-venv ``` To deactive the virtual environment, run: ```bash deactivate ``` 3. **Install Dependencies:** ```bash pip install -r web/requirements.txt -r builder/requirements.txt ``` If pip is not installed, run: ```bash sudo apt install python3-pip ``` 4. **Install and Run Redis:** Use your package manager to install Redis: ```bash sudo apt install redis-server ``` Ensure the Redis server is running: ```bash sudo systemctl status redis-server ``` 5. **Execute the Application:** - For a development environment with auto-reload, run: ```bash python3 web/main.py ``` To change the port, use the `--port` argument: ```bash python3 web/main.py --port 9000 ``` - For a production environment, use: ```bash uvicorn web.main:app --host 0.0.0.0 --port 8080 ``` During the coding and testing phases, use the development environment to easily debug and make changes with auto-reload enabled. When deploying the app for end users, use the production environment to ensure better performance, scalability, and security. The application will automatically set up the required base directory at `./base` upon first execution. You may customize this path by setting the `CBS_BASEDIR` environment variable. 6. **Access the Web Interface:** Once the application is running, you can access the interface in your web browser at http://localhost:8080. The default port is 8080, or the value of the `WEB_PORT` environment variable if set. You can override this by passing the `--port` argument when running the application directly (e.g., `python3 web/main.py --port 9000`) or when using uvicorn (e.g., `uvicorn web.main:app --port 5000`). Refer to the [uvicorn documentation](https://www.uvicorn.org/) for additional configuration options. ## Directory Structure The default directory structure is established as follows: ``` /home/ └── CustomBuild └── base ├── ardupilot (used by the web component) ├── artifacts ├── configs | └── remotes.json (auto-generated, see examples/remotes.json.sample) ├── secrets | └── reload_token (optional) ├── tmp └── ardupilot (used by the builder component) ``` The build artifacts are organized under the `base/artifacts` subdirectory. ## Acknowledgements This project includes many valuable contributions made during the Google Summer of Code 2021. For more information, please see the [GSOC 2021 Blog Post](https://discuss.ardupilot.org/t/gsoc-2021-custom-firmware-builder/74946).