diff --git a/docs/figures/cox_hexa_x.png b/docs/figures/cox_hexa_x.png new file mode 100644 index 0000000..e9cfcd8 Binary files /dev/null and b/docs/figures/cox_hexa_x.png differ diff --git a/docs/figures/cox_quad_x.png b/docs/figures/cox_quad_x.png new file mode 100644 index 0000000..771656d Binary files /dev/null and b/docs/figures/cox_quad_x.png differ diff --git a/docs/figures/fixwing.png b/docs/figures/fixwing.png new file mode 100644 index 0000000..19c2892 Binary files /dev/null and b/docs/figures/fixwing.png differ diff --git a/docs/figures/hexa_+.png b/docs/figures/hexa_+.png new file mode 100644 index 0000000..e3a3db1 Binary files /dev/null and b/docs/figures/hexa_+.png differ diff --git a/docs/figures/hexa_x.png b/docs/figures/hexa_x.png new file mode 100644 index 0000000..b2c0371 Binary files /dev/null and b/docs/figures/hexa_x.png differ diff --git a/docs/figures/octo_+.png b/docs/figures/octo_+.png new file mode 100644 index 0000000..1be7b1a Binary files /dev/null and b/docs/figures/octo_+.png differ diff --git a/docs/figures/octo_x.png b/docs/figures/octo_x.png new file mode 100644 index 0000000..6c68217 Binary files /dev/null and b/docs/figures/octo_x.png differ diff --git a/docs/figures/quad_+.png b/docs/figures/quad_+.png new file mode 100644 index 0000000..bfbf2bb Binary files /dev/null and b/docs/figures/quad_+.png differ diff --git a/docs/figures/quad_x.png b/docs/figures/quad_x.png new file mode 100644 index 0000000..1c5947c Binary files /dev/null and b/docs/figures/quad_x.png differ diff --git a/docs/introduction/build.md b/docs/introduction/build.md new file mode 100644 index 0000000..db99eef --- /dev/null +++ b/docs/introduction/build.md @@ -0,0 +1,150 @@ +## Directory Structure + +Understanding the directory structure of FMT-Firmware is crucial before compiling the firmware. Below is a general overview of the typical directory structure you can expect to find in the FMT-Firmware project: + +``` +FMT-Firmware/ +|-- rtos/ +| |-- rt-thread +|-- src/ +| |-- driver +| |-- hal +| |-- lib +| |-- model +| |-- module +| |-- protocol +| |-- task +| |-- startup.c +| |-- ... +|-- target/ +| |-- amov +| |-- coolflt +| |-- cuav +| |-- cubepilot +| |-- minimum +| |-- pixhawk +| |-- qemu +|-- unit_test/ +| |-- test_case1.c +| |-- ... +|-- .clang-format +|-- README.md +|-- LICENSE +|-- .gitignore +|-- ... + +``` + +Explanation of directories and files: + +1. **src/**: This directory holds the primary source code files of the firmware. The `startup.c` file is typically the entry point of the firmware. Other directories, such as `driver`, `hal`, `lib`, `modules`, etc., represent distinct components of the firmware, making it modular and organized. +2. **rtos/**: Within this directory, you'll find the code related to the Real-Time Operating System (RTOS) utilized in the FMT-Firmware project. It specifically contains the RTOS implementation, and in this case, it utilizes the "rt-thread" RTOS. +3. **target/**: This folder accommodates the Board Support Package (BSP) specific to the hardware targeted for the firmware. The BSP is a crucial component that facilitates interaction between the firmware and the hardware it runs on. +4. **unit_test/**: The `unit_test/` directory comprises code for unit tests, which play a vital role in testing individual components or units of the firmware in isolation, ensuring robustness and correctness. Unit tests are essential for maintaining the reliability of the firmware. + +This enhanced explanation provides a clearer understanding of the directory structure of the FMT-Firmware project, highlighting the role and content of each directory within the context of firmware development. + + +## Build + +To learn how to build and download the firmware, kindly consult the README file of the each BSP. For this explanation, we will use ICF5 as an example to illustrate the firmware building process. The README file typically provides detailed instructions on the necessary steps, dependencies, and configurations required for a successful firmware compilation and download. + +- [AMOV ICF5](https://github.com/Firmament-Autopilot/FMT-Firmware/blob/master/target/amov/icf5/README.md) +- [CUAV V5+](https://github.com/Firmament-Autopilot/FMT-Firmware/blob/master/target/cuav/v5_plus/README.md) +- [Pixhawk 4](https://github.com/Firmament-Autopilot/FMT-Firmware/blob/master/target/pixhawk/fmu-v5/README.md) +- [Pixhawk 2.4.6](https://github.com/Firmament-Autopilot/FMT-Firmware/blob/master/target/pixhawk/fmu-v2/README.md) +- [QEMU vexpress-a9](https://github.com/Firmament-Autopilot/FMT-Firmware/blob/master/target/qemu/qemu-vexpress-a9/README.md) + +### Build Firmware + +To build the firmware for a quadcopter, follow these steps: + +1. Navigate to the relevant directory for the quadcopter target: + +``` +cd FMT-Firmware/target/amov/icf5 +``` + +2. Initiate the build process with the `scons` command: + +``` +scons -j4 +``` + +The `-j4` flag enables parallel building with 4 jobs, accelerating the build process and reducing compilation time. By default, the firmware is built for the Quadcopter vehicle (`vehicle=Multicopter --airframe=1`). For other vehicle and airframe types, please refer to the [Vehicle/Airframe](introduction/vehicle_type.md) section. + +### Download Firmware + +There are two methods available for downloading firmware to the hardware: + +1. **Download Script**: To use the download script, navigate to the `icf5` directory and execute the command `python3 uploader.py`. Ensure that your hardware is connected via USB. + + ```shell + FMT-Firmware\target\amov\icf5> python .\uploader.py + waiting for the bootloader... + Error: no serial connection found + wait for connect fmt-fmu... + Error: no serial connection found + wait for connect fmt-fmu... + + Found board id: 50,0 bootloader version: 5 on COM7 + sn: 000000000000000000000000 + chip: 22020419 + family: b'GD32F4[5|7]x' + revision: b'?' + flash: 1015808 bytes + Windowed mode: False + + Erase : [====================] 100.0% + Program: [====================] 100.0% + Verify : [====================] 100.0% + Rebooting. Elapsed Time 9.687 + ``` + + > If you encounter a `"ModuleNotFoundError: No module named 'serial'"` error, it indicates that the **pyserial** component is missing. You can install it by running `pip3 install pyserial`. + +If the script is unable to automatically detect the port, you have the option to specify the port manually using the `--port` option. For example, you can use the following command to indicate the port explicitly: + +``` +python3 uploader.py --port COM3 +``` + + + +2. **J-Link**: If you have a JLink, you can connect it to the board's debug port to download the firmware. For more detailed information, please refer to the [Debug](https://firmament-autopilot.github.io/FMT-DOCS/#/introduction/debug) section in the documentation. + + > Take caution not to overwrite the bootloader during the firmware download process. + +These two methods provide different options for downloading the firmware onto the hardware, offering flexibility and ease of use to suit your specific requirements. + +When the system is up and running, the system banner is displayed either via `serial0` (serial console) or can be viewed by entering `boot_log` in the QGroundControl (QGC) mavlink console. This banner provides important information about the system's status and configurations, allowing users to monitor the system's behavior and ensure it is functioning correctly. + +``` +-----------FMT Bootloader v1.x----------- +Board Type: 50 +Board Revision: 0 +Board Flash Size: 1015808 +App Load Address: 0x8010000 + + _____ __ + / __(_)_____ _ ___ ___ _ ___ ___ / /_ + / _// / __/ ' \/ _ `/ ' \/ -_) _ \/ __/ +/_/ /_/_/ /_/_/_/\_,_/_/_/_/\__/_//_/\__/ +Firmware.....................FMT FW v0.5.5 +Kernel....................RT-Thread v4.0.3 +RAM.................................448 KB +Target...........................Amov-ICF5 +Vehicle........................Multicopter +Airframe.................................1 +INS Model..................Base INS v0.3.2 +FMS Model..................Base FMS v0.4.0 +Control Model.......Base Controller v0.2.4 +Task Initialize: + mavobc................................OK + mavgcs................................OK + logger................................OK + status................................OK + vehicle...............................OK + +``` + diff --git a/docs/introduction/download.md b/docs/introduction/download.md new file mode 100644 index 0000000..ae15265 --- /dev/null +++ b/docs/introduction/download.md @@ -0,0 +1,102 @@ + +## Download Firmware + +The FMT code is available on [Github](https://github.com/Firmament-Autopilot). To download the FMT-Firmware, use the following git command. If you don't have [git](https://git-scm.com/downloads) installed, please install it before proceeding. + +``` +git clone https://github.com/Firmament-Autopilot/FMT-Firmware.git --recursive --shallow-submodules +``` + +> Please be aware that the FMT-Firmware includes submodules. To ensure you download the submodules as well, use the *--recursive* flag when fetching the repository. + +## Toolchain + +FMT utilizes cross-platform toolchains, enabling its development across various operating systems, such as Windows, Linux, and Mac. This flexibility ensures that developers can work on the project seamlessly, regardless of their preferred platform. + +### Compiler + +FMT-Firmware specifically relies on the **arm-none-eabi- toolchain 7-2018-q2-update** version, which can be obtained from [this link](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads). It is essential to adhere to this specified compiler version to prevent any unforeseen errors or unpredictable behaviors during development. Using other compiler versions is not recommended to maintain stability and consistency in the project. + +After installing the compiler, the next step is to create a new environment variable called `RTT_EXEC_PATH`. This variable should point to the full path of the compiler's bin directory. Here's how you can set up the environment variable: + +1. Find the path to the compiler's bin directory, which contains executable files like `gcc`, `gdb`, etc. + +2. Set the `RTT_EXEC_PATH` environment variable to this full path. The process varies depending on your operating system: + + - **Windows**: Open the Control Panel, go to System and Security > System > Advanced system settings > Environment Variables. Click on "New" under "User variables" and enter the variable name as `RTT_EXEC_PATH` and the variable value as the full path to the compiler's bin directory. + + + + - **Linux/Mac**: Open a terminal and edit the shell configuration file (e.g., `~/.bashrc`, `~/.bash_profile`, or `~/.zshrc`, depending on your shell). Add the following line to the file: + + ```bash + export RTT_EXEC_PATH=/path/to/compiler/bin + ``` + + Save the file and run `source ~/.bashrc` (or the corresponding file for your shell) to apply the changes to the current terminal session. + +By setting the `RTT_EXEC_PATH` environment variable, you enable the system to locate and use the compiler tools easily during the development process. + +### Construction Tool + +FMT employs SCons as its construction tool, which serves as an enhanced and cross-platform alternative to the traditional Make utility. SCons configuration files are written in Python, offering a user-friendly and powerful approach to address build-related challenges. Python's flexibility and ease of use make configuring the build process a more intuitive and efficient experience. With SCons, developers can enjoy a streamlined and effective build system that adapts smoothly across different platforms. + +Prior to installing SCons, it is essential to verify whether Python 3 is already installed on your system. If you don't have Python 3 installed, you can download it from [the official website](https://www.python.org/downloads/). Python serves as a prerequisite for SCons, as SCons configuration files are written in Python scripts. Once Python 3 is installed, you can proceed with the installation of SCons to enable a smoother and more efficient build process for your projects. + +After ensuring that Python 3 is installed on your system, follow these steps in the terminal: + +1. To install the latest version of SCons, enter the following command: + + ```bash + > pip3 install scons + ``` + +2. Once the installation is complete, you can check if SCons was installed successfully by entering the following command: + + ```bash + > scons --version + ``` + +3. If the version information is printed on the terminal, it indicates that SCons has been installed successfully, and you are now ready to use it as your construction tool for projects. + + ```bash + > scons --version + SCons by Steven Knight et al.: + SCons: v4.4.0.fc8d0ec215ee6cba8bc158ad40c099be0b598297, Sat, 30 Jul 2022 14:11:34 -0700, by bdbaddog on M1Dog2021 + SCons path: ['C:\\Users\\zouji\\AppData\\Local\\Programs\\Python\\Python311\\Lib\\site-packages\\SCons'] + Copyright (c) 2001 - 2022 The SCons Foundation + ``` + +### IDE + +Using Visual Studio Code (VS Code) as the Integrated Development Environment (IDE) is highly recommended for working with FMT and SCons. You can download VS Code from [the official website](https://code.visualstudio.com/). + +VS Code provides a powerful and user-friendly development environment with a wide range of extensions and features, making it ideal for working on projects like FMT that utilize SCons as the build tool. Its flexibility, extensibility, and compatibility with various programming languages make it a popular choice among developers. + +To begin coding for the FMT-Firmware project in Visual Studio Code, follow these steps: + +1. Open Visual Studio Code. +2. Click on the "File" menu in the top-left corner. +3. Select "Open Folder" from the dropdown menu. +4. A file explorer dialog will appear. Navigate to the location where you have the FMT-Firmware folder stored. +5. Select the FMT-Firmware folder and click "Open." + +Now, you have the FMT-Firmware project opened in Visual Studio Code, and you can start coding, modifying, and managing the project using the various features and extensions provided by the IDE. Happy coding! + + + + +Absolutely, installing useful Visual Studio Code (VS Code) plugins can significantly enhance your development experience when working with the FMT-Firmware project. Two essential plugins for the FMT-Firmware project are: + +1. **C/C++**: This plugin provides excellent support for C and C++ languages in VS Code, offering features like code highlighting, IntelliSense, code navigation, and debugging capabilities tailored for these languages. +2. **Clang-Format**: Clang-Format is a code formatting tool for C, C++, and other programming languages. The Clang-Format plugin in VS Code allows you to automatically format your code according to specific style guidelines, ensuring consistent and readable code. + +To install these plugins, follow these steps: + +1. Open Visual Studio Code. +2. Click on the "Extensions" icon on the left sidebar (or use the shortcut `Ctrl+Shift+X` or `Cmd+Shift+X` on macOS). +3. In the Extensions marketplace search bar, type "C/C++" and "Clang-Format." +4. Click on the "Install" button for each plugin. +5. After installation, you may need to restart Visual Studio Code to activate the plugins. + +With these plugins installed, your development environment will be better equipped to handle the intricacies of the FMT-Firmware project, making coding and formatting tasks more efficient and convenient. diff --git a/docs/introduction/quickstart.md b/docs/introduction/quickstart.md deleted file mode 100644 index 5747db1..0000000 --- a/docs/introduction/quickstart.md +++ /dev/null @@ -1,76 +0,0 @@ - -## Download - -The FMT code is hosted on [Github](https://github.com/Firmament-Autopilot). Use following git command to download FMT-Firmware. If you don't have [git](https://git-scm.com/downloads) installed, please install it first. - -``` -git clone https://github.com/Firmament-Autopilot/FMT-Firmware.git --recursive --shallow-submodules -``` - -> Note that FMT-Firmware contains submodules, use *--recursive* to download submodule as well. - -## Toolchain - -FMT uses the cross-platform toolchains, therefore can be developed in Windows/Linux/Mac. - -### Compiler - -FMT-Firmware use [arm-none-eabi- toolchain *7-2018-q2-update*](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads). Do not use other compiler version to avoid unexpected errors and behaviors. - -When compiler has been installed, you need create a new enviroment variable `RTT_EXEC_PATH`， which points to the full path of the compiler's bin directory. - -**Windows**: - - - -**Linux**： - -Please add the following command at the end of ~/.bashrc, and replace the `` with the compiler's full path. - -``` -export RTT_EXEC_PATH=/bin -``` - -### Construction Tool - -FMT use SCons as the construction tool. Which is an improved, cross-platform substite for classic Make utility. SCons configuration files are Python scripts, which is easier to use and powerful to solve build problems. - -Before installing SCons, you need to make sure that your system has python3 installed. You can go to [the website](https://www.python.org/downloads/) to download python if it's not installed on your system. - -Then enter `pip3 install scons` in terminal to install the latest version of SCons. When complete, enter `scons --version` and if version information is printed, that means scons installed successfully. - -``` -PS C:\Users\zouji> scons --version -SCons by Steven Knight et al.: - SCons: v4.4.0.fc8d0ec215ee6cba8bc158ad40c099be0b598297, Sat, 30 Jul 2022 14:11:34 -0700, by bdbaddog on M1Dog2021 - SCons path: ['C:\\Users\\zouji\\AppData\\Local\\Programs\\Python\\Python311\\Lib\\site-packages\\SCons'] -Copyright (c) 2001 - 2022 The SCons Foundation -``` - -### IDE - -It's recommended to use the Visual Studio Code as the IDE，you can go to [the website](https://code.visualstudio.com) to download it. - -To start coding, simply click *File->Open Folder* and select the FMT-Firmware folder. - - - -> For ease of use, you can install some useful VSCode plugins, such as C/C++, Clang-Format. - -## Build - -Before compiling the firmware, you need to know the directory structure of FMT-Firmware: - - - -The main code iis stored in the src directory, and the target directory is the BSP (Board Support Package) for each hardware platform, containing peripheral driver code. - -About how to build and download the firmware, please refer to the BSP's README: - -- [AMOV ICF5](https://github.com/Firmament-Autopilot/FMT-Firmware/blob/master/target/amov/icf5/README.md) -- [CUAV V5+](https://github.com/Firmament-Autopilot/FMT-Firmware/blob/master/target/cuav/v5_plus/README.md) -- [Pixhawk 4](https://github.com/Firmament-Autopilot/FMT-Firmware/blob/master/target/pixhawk/fmu-v5/README.md) -- [Pixhawk 2.4.6](https://github.com/Firmament-Autopilot/FMT-Firmware/blob/master/target/pixhawk/fmu-v2/README.md) - -- [QEMU vexpress-a9](https://github.com/Firmament-Autopilot/FMT-Firmware/blob/master/target/qemu/qemu-vexpress-a9/README.md) - diff --git a/docs/introduction/vehicle_type.md b/docs/introduction/vehicle_type.md new file mode 100644 index 0000000..80abd78 --- /dev/null +++ b/docs/introduction/vehicle_type.md @@ -0,0 +1,50 @@ +## Vehicle/Airframe + +FMT is capable of controlling many vehicles and airframes, and it's easy to add algorithms to control even more vehicles. + +This document aims to list these options. However, please note that it's still a work in progress and not yet complete. + +We gladly welcome the contribution to support a broader range of vehicle types. + +#### Multicopter +| Airframe | Build Command | Description | +| ------------------------------- | ----------------------------------------- | ------------------------------------ | +| Quadcopter x, Airframe=1 | scons --vehicle=Multicopter --airframe=1 | ![quad_x](../figures/quad_x.png) | +| Quadcopter +, Airframe=2 | scons --vehicle=Multicopter --airframe=2 | ![quad_+](../figures/quad_+.png) | +| Coxial Quadcopter x, Airframe=3 | scons --vehicle=Multicopter --airframe=3 | ![quad_+](../figures/cox_quad_x.png) | +| Hexacopter x, Airframe=4 | scons --vehicle=Multicopter --airframe=4 | ![quad_+](../figures/hexa_x.png) | +| Hexacopter +, Airframe=5 | scons --vehicle=Multicopter --airframe=5 | ![quad_+](../figures/hexa_+.png) | +| Coxial Hexacopter x, Airframe=6 | scons --vehicle=Multicopter --airframe=6 | ![quad_+](../figures/cox_hexa_x.png) | +| Octocopter x, Airframe=7 | scons --vehicle=Multicopter --airframe=7 | ![quad_+](../figures/octo_x.png) | +| Octocopter +, Airframe=8 | scons --vehicle=Multicopter --airframe=8 | ![quad_+](../figures/octo_+.png) | + +#### Fixwing +| Airframe | Build Command | Description | +| ---------------------------- | ------------------------------------ | --------------------------------- | +| Standard Fixwing, Airframe=1 | scons --vehicle=Fixwing --airframe=1 | ![quad_x](../figures/fixwing.png) | + + +## Show Vehicle/Airframe Type +When the system is up and running, the vehicle and airframe are displayed in the system banner. You can also use the `boot_log` command to view the system banner. +```shell + + _____ __ + / __(_)_____ _ ___ ___ _ ___ ___ / /_ + / _// / __/ ' \/ _ `/ ' \/ -_) _ \/ __/ +/_/ /_/_/ /_/_/_/\_,_/_/_/_/\__/_//_/\__/ +Firmware.....................FMT FW v0.5.5 +Kernel....................RT-Thread v4.0.3 +RAM.................................448 KB +Target...........................Amov-ICF5 +Vehicle........................Multicopter +Airframe.................................1 +INS Model..................Base INS v0.3.2 +FMS Model..................Base FMS v0.4.0 +Control Model.......Base Controller v0.2.4 +Task Initialize: + mavobc................................OK + mavgcs................................OK + logger................................OK + status................................OK + vehicle...............................OK +``` diff --git a/docs/sidebar.md b/docs/sidebar.md index f7ac722..21e97ad 100644 --- a/docs/sidebar.md +++ b/docs/sidebar.md @@ -4,7 +4,9 @@ - Getting started - - [Quick Start](introduction/quickstart.md) + - [Download](introduction/download.md) + - [Build](introduction/build.md) + - [Vehicle/Airframe](introduction/vehicle_type.md) - [Configuration](introduction/configuration/configuration.md) - [Console Configuration](introduction/configuration/console_config.md) - [Mavproxy Configuration](introduction/configuration/mavproxy_config.md)