diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..bff7db90f --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,55 @@ +name: Deploy Documentation + +on: + push: + branches: + - main + paths: + - 'docs/**' + - 'mkdocs.yml' + - 'docs-requirements.txt' + - '.github/workflows/docs.yml' + tags: + - 'v[0-9]+.[0-9]+.[0-9]+' # release tags only, not -rc + pull_request: + paths: + - 'docs/**' + - 'mkdocs.yml' + - 'docs-requirements.txt' + - '.github/workflows/docs.yml' + workflow_dispatch: + +permissions: + contents: write + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + with: + fetch-depth: 0 + + - name: Install uv + uses: astral-sh/setup-uv@v7 + + - name: Configure git for mike + if: github.event_name != 'pull_request' + run: | + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + + - name: Build docs (PR check) + if: github.event_name == 'pull_request' + run: uv run --with-requirements docs-requirements.txt mkdocs build --strict + + - name: Deploy as latest (main branch) + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + run: uv run --with-requirements docs-requirements.txt mike deploy --push --update-aliases latest + + - name: Deploy release version + if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/') + run: | + # Extract minor version from tag, e.g. v2.11.2 -> v2.11 + VERSION=$(echo "${GITHUB_REF_NAME}" | sed 's/\.[0-9]*$//') + uv run --with-requirements docs-requirements.txt mike deploy --push --update-aliases "${VERSION}" stable diff --git a/.gitignore b/.gitignore index e130e83fd..27ec494cc 100644 --- a/.gitignore +++ b/.gitignore @@ -4,8 +4,8 @@ /*.user /*.user.* /doc/ -build*/ -cmake-build-*/ +/build*/ +/cmake-build-*/ /debian/ /*.vscode radio/src/tests/googletest* diff --git a/docs-requirements.txt b/docs-requirements.txt new file mode 100644 index 000000000..eb4a5cbd9 --- /dev/null +++ b/docs-requirements.txt @@ -0,0 +1,4 @@ +mkdocs>=1.6 +mkdocs-material>=9.5 +mkdocs-minify-plugin>=0.8 +mike>=2.0 diff --git a/docs/assets/images/ACCESS.png b/docs/assets/images/ACCESS.png new file mode 100644 index 000000000..a8892d7b0 Binary files /dev/null and b/docs/assets/images/ACCESS.png differ diff --git a/docs/assets/images/DSM2.png b/docs/assets/images/DSM2.png new file mode 100644 index 000000000..0b8cd434e Binary files /dev/null and b/docs/assets/images/DSM2.png differ diff --git a/docs/assets/images/EdgeTX_logo.png b/docs/assets/images/EdgeTX_logo.png new file mode 100644 index 000000000..9c5aca4af Binary files /dev/null and b/docs/assets/images/EdgeTX_logo.png differ diff --git a/docs/assets/images/MULTI.png b/docs/assets/images/MULTI.png new file mode 100644 index 000000000..c39cf46d4 Binary files /dev/null and b/docs/assets/images/MULTI.png differ diff --git a/docs/assets/images/PPM.png b/docs/assets/images/PPM.png new file mode 100644 index 000000000..1e912b45f Binary files /dev/null and b/docs/assets/images/PPM.png differ diff --git a/docs/assets/images/PXX.png b/docs/assets/images/PXX.png new file mode 100644 index 000000000..9daf94d79 Binary files /dev/null and b/docs/assets/images/PXX.png differ diff --git a/docs/assets/images/SBUS Normal.png b/docs/assets/images/SBUS Normal.png new file mode 100644 index 000000000..8d7a5c665 Binary files /dev/null and b/docs/assets/images/SBUS Normal.png differ diff --git a/docs/assets/images/XFIRE.png b/docs/assets/images/XFIRE.png new file mode 100644 index 000000000..984da2f92 Binary files /dev/null and b/docs/assets/images/XFIRE.png differ diff --git a/docs/assets/images/build/icd/QtBreakpoint.png b/docs/assets/images/build/icd/QtBreakpoint.png new file mode 100644 index 000000000..3c7af2721 Binary files /dev/null and b/docs/assets/images/build/icd/QtBreakpoint.png differ diff --git a/docs/assets/images/build/icd/QtICD.png b/docs/assets/images/build/icd/QtICD.png new file mode 100644 index 000000000..466dfab4b Binary files /dev/null and b/docs/assets/images/build/icd/QtICD.png differ diff --git a/docs/assets/images/build/icd/TX16S_SWD.jpg b/docs/assets/images/build/icd/TX16S_SWD.jpg new file mode 100644 index 000000000..36cfa7646 Binary files /dev/null and b/docs/assets/images/build/icd/TX16S_SWD.jpg differ diff --git a/docs/assets/images/build/icd/TX16S_power_override.jpg b/docs/assets/images/build/icd/TX16S_power_override.jpg new file mode 100644 index 000000000..5f9b78bd4 Binary files /dev/null and b/docs/assets/images/build/icd/TX16S_power_override.jpg differ diff --git a/docs/assets/images/build/icd/in-circuit-debugging_TX16S.jpg b/docs/assets/images/build/icd/in-circuit-debugging_TX16S.jpg new file mode 100644 index 000000000..b8fced349 Binary files /dev/null and b/docs/assets/images/build/icd/in-circuit-debugging_TX16S.jpg differ diff --git a/docs/assets/images/build/linux/EdgeTX_simulator_Linux.png b/docs/assets/images/build/linux/EdgeTX_simulator_Linux.png new file mode 100644 index 000000000..97ca1c890 Binary files /dev/null and b/docs/assets/images/build/linux/EdgeTX_simulator_Linux.png differ diff --git a/docs/assets/images/build/qtcreator/QtCodeCompletion.png b/docs/assets/images/build/qtcreator/QtCodeCompletion.png new file mode 100644 index 000000000..ffb49c031 Binary files /dev/null and b/docs/assets/images/build/qtcreator/QtCodeCompletion.png differ diff --git a/docs/assets/images/build/qtcreator/QtCreatorBareMetal.png b/docs/assets/images/build/qtcreator/QtCreatorBareMetal.png new file mode 100644 index 000000000..035eb8aa0 Binary files /dev/null and b/docs/assets/images/build/qtcreator/QtCreatorBareMetal.png differ diff --git a/docs/assets/images/build/qtcreator/QtCreatorBuildCompleted.png b/docs/assets/images/build/qtcreator/QtCreatorBuildCompleted.png new file mode 100644 index 000000000..7f9ca3153 Binary files /dev/null and b/docs/assets/images/build/qtcreator/QtCreatorBuildCompleted.png differ diff --git a/docs/assets/images/build/qtcreator/QtCreatorBuildEnvironment.png b/docs/assets/images/build/qtcreator/QtCreatorBuildEnvironment.png new file mode 100644 index 000000000..2423b2d7b Binary files /dev/null and b/docs/assets/images/build/qtcreator/QtCreatorBuildEnvironment.png differ diff --git a/docs/assets/images/build/qtcreator/QtCreatorBuildSteps.png b/docs/assets/images/build/qtcreator/QtCreatorBuildSteps.png new file mode 100644 index 000000000..6aae2cc83 Binary files /dev/null and b/docs/assets/images/build/qtcreator/QtCreatorBuildSteps.png differ diff --git a/docs/assets/images/build/qtcreator/QtCreatorCMakeConfiguration.png b/docs/assets/images/build/qtcreator/QtCreatorCMakeConfiguration.png new file mode 100644 index 000000000..25362c2c8 Binary files /dev/null and b/docs/assets/images/build/qtcreator/QtCreatorCMakeConfiguration.png differ diff --git a/docs/assets/images/build/qtcreator/QtCreatorCMakeOptions.png b/docs/assets/images/build/qtcreator/QtCreatorCMakeOptions.png new file mode 100644 index 000000000..0a48494d4 Binary files /dev/null and b/docs/assets/images/build/qtcreator/QtCreatorCMakeOptions.png differ diff --git a/docs/assets/images/build/qtcreator/QtCreatorCompilers.png b/docs/assets/images/build/qtcreator/QtCreatorCompilers.png new file mode 100644 index 000000000..6668925b1 Binary files /dev/null and b/docs/assets/images/build/qtcreator/QtCreatorCompilers.png differ diff --git a/docs/assets/images/build/qtcreator/QtCreatorDebuggers.png b/docs/assets/images/build/qtcreator/QtCreatorDebuggers.png new file mode 100644 index 000000000..ff0be5a46 Binary files /dev/null and b/docs/assets/images/build/qtcreator/QtCreatorDebuggers.png differ diff --git a/docs/assets/images/build/qtcreator/QtCreatorDeployTarget.png b/docs/assets/images/build/qtcreator/QtCreatorDeployTarget.png new file mode 100644 index 000000000..9a725f7be Binary files /dev/null and b/docs/assets/images/build/qtcreator/QtCreatorDeployTarget.png differ diff --git a/docs/assets/images/build/qtcreator/QtCreatorDevices.png b/docs/assets/images/build/qtcreator/QtCreatorDevices.png new file mode 100644 index 000000000..315fe7fdf Binary files /dev/null and b/docs/assets/images/build/qtcreator/QtCreatorDevices.png differ diff --git a/docs/assets/images/build/qtcreator/QtCreatorJLink.png b/docs/assets/images/build/qtcreator/QtCreatorJLink.png new file mode 100644 index 000000000..fa9e77b50 Binary files /dev/null and b/docs/assets/images/build/qtcreator/QtCreatorJLink.png differ diff --git a/docs/assets/images/build/qtcreator/QtCreatorKits.png b/docs/assets/images/build/qtcreator/QtCreatorKits.png new file mode 100644 index 000000000..95e3fc489 Binary files /dev/null and b/docs/assets/images/build/qtcreator/QtCreatorKits.png differ diff --git a/docs/assets/images/build/qtcreator/QtCreatorProjectKitSelection.png b/docs/assets/images/build/qtcreator/QtCreatorProjectKitSelection.png new file mode 100644 index 000000000..039bf6a50 Binary files /dev/null and b/docs/assets/images/build/qtcreator/QtCreatorProjectKitSelection.png differ diff --git a/docs/assets/images/build/qtcreator/QtCreator_01.png b/docs/assets/images/build/qtcreator/QtCreator_01.png new file mode 100644 index 000000000..d4a3fc36f Binary files /dev/null and b/docs/assets/images/build/qtcreator/QtCreator_01.png differ diff --git a/docs/assets/images/build/qtcreator/QtGDBtimeout.png b/docs/assets/images/build/qtcreator/QtGDBtimeout.png new file mode 100644 index 000000000..ac6b9da8d Binary files /dev/null and b/docs/assets/images/build/qtcreator/QtGDBtimeout.png differ diff --git a/docs/assets/images/build/rcvr_yt_gitpod.jpg b/docs/assets/images/build/rcvr_yt_gitpod.jpg new file mode 100644 index 000000000..6b2780a2a Binary files /dev/null and b/docs/assets/images/build/rcvr_yt_gitpod.jpg differ diff --git a/docs/assets/images/build/win10/TortoiseGit.png b/docs/assets/images/build/win10/TortoiseGit.png new file mode 100644 index 000000000..094638176 Binary files /dev/null and b/docs/assets/images/build/win10/TortoiseGit.png differ diff --git a/docs/assets/images/build/win10/cmake_01.png b/docs/assets/images/build/win10/cmake_01.png new file mode 100644 index 000000000..8224651dd Binary files /dev/null and b/docs/assets/images/build/win10/cmake_01.png differ diff --git a/docs/assets/images/build/win10/gnu_arm_10-2020-q4.png b/docs/assets/images/build/win10/gnu_arm_10-2020-q4.png new file mode 100644 index 000000000..af529d02f Binary files /dev/null and b/docs/assets/images/build/win10/gnu_arm_10-2020-q4.png differ diff --git a/docs/assets/images/build/win10/pip.png b/docs/assets/images/build/win10/pip.png new file mode 100644 index 000000000..fc2546eba Binary files /dev/null and b/docs/assets/images/build/win10/pip.png differ diff --git a/docs/assets/images/build/win10/pthreads.png b/docs/assets/images/build/win10/pthreads.png new file mode 100644 index 000000000..7b0689f40 Binary files /dev/null and b/docs/assets/images/build/win10/pthreads.png differ diff --git a/docs/assets/images/build/win10/python2_01.png b/docs/assets/images/build/win10/python2_01.png new file mode 100644 index 000000000..8cb18a17b Binary files /dev/null and b/docs/assets/images/build/win10/python2_01.png differ diff --git a/docs/assets/images/build/win10/python2_02.png b/docs/assets/images/build/win10/python2_02.png new file mode 100644 index 000000000..d8a56ab0b Binary files /dev/null and b/docs/assets/images/build/win10/python2_02.png differ diff --git a/docs/assets/images/build/win10/python2_03.png b/docs/assets/images/build/win10/python2_03.png new file mode 100644 index 000000000..8505be684 Binary files /dev/null and b/docs/assets/images/build/win10/python2_03.png differ diff --git a/docs/assets/images/build/win10/python3_01.png b/docs/assets/images/build/win10/python3_01.png new file mode 100644 index 000000000..71ce48fa4 Binary files /dev/null and b/docs/assets/images/build/win10/python3_01.png differ diff --git a/docs/assets/images/build/win10/python3_02.png b/docs/assets/images/build/win10/python3_02.png new file mode 100644 index 000000000..2c322f276 Binary files /dev/null and b/docs/assets/images/build/win10/python3_02.png differ diff --git a/docs/assets/images/build/win10/python3_03.png b/docs/assets/images/build/win10/python3_03.png new file mode 100644 index 000000000..f5ed7b3c6 Binary files /dev/null and b/docs/assets/images/build/win10/python3_03.png differ diff --git a/docs/assets/images/build/win10/python3_pathlength.png b/docs/assets/images/build/win10/python3_pathlength.png new file mode 100644 index 000000000..c821108b8 Binary files /dev/null and b/docs/assets/images/build/win10/python3_pathlength.png differ diff --git a/docs/assets/images/build/win10/qt_env_var.png b/docs/assets/images/build/win10/qt_env_var.png new file mode 100644 index 000000000..cb49ce093 Binary files /dev/null and b/docs/assets/images/build/win10/qt_env_var.png differ diff --git a/docs/assets/images/build/win10/qt_install_01.png b/docs/assets/images/build/win10/qt_install_01.png new file mode 100644 index 000000000..4ca429ba2 Binary files /dev/null and b/docs/assets/images/build/win10/qt_install_01.png differ diff --git a/docs/assets/images/build/win10/qt_install_02.png b/docs/assets/images/build/win10/qt_install_02.png new file mode 100644 index 000000000..a85c39684 Binary files /dev/null and b/docs/assets/images/build/win10/qt_install_02.png differ diff --git a/docs/assets/images/build/win10/qt_install_03.png b/docs/assets/images/build/win10/qt_install_03.png new file mode 100644 index 000000000..e074b9516 Binary files /dev/null and b/docs/assets/images/build/win10/qt_install_03.png differ diff --git a/docs/assets/images/build/win10/qt_signup.png b/docs/assets/images/build/win10/qt_signup.png new file mode 100644 index 000000000..4571e3793 Binary files /dev/null and b/docs/assets/images/build/win10/qt_signup.png differ diff --git a/docs/assets/images/build/win10/sdl.png b/docs/assets/images/build/win10/sdl.png new file mode 100644 index 000000000..3abfc4671 Binary files /dev/null and b/docs/assets/images/build/win10/sdl.png differ diff --git a/docs/assets/images/build/win10/vscommunity2019_cpp_01.png b/docs/assets/images/build/win10/vscommunity2019_cpp_01.png new file mode 100644 index 000000000..5606e3194 Binary files /dev/null and b/docs/assets/images/build/win10/vscommunity2019_cpp_01.png differ diff --git a/docs/assets/images/build/win10/vscommunity2019_cpp_02.png b/docs/assets/images/build/win10/vscommunity2019_cpp_02.png new file mode 100644 index 000000000..5d4ede123 Binary files /dev/null and b/docs/assets/images/build/win10/vscommunity2019_cpp_02.png differ diff --git a/docs/assets/images/build/win10/vscommunity2019_cpp_03.png b/docs/assets/images/build/win10/vscommunity2019_cpp_03.png new file mode 100644 index 000000000..fccebad4d Binary files /dev/null and b/docs/assets/images/build/win10/vscommunity2019_cpp_03.png differ diff --git a/docs/assets/images/build/win10_msys2/build_companion.png b/docs/assets/images/build/win10_msys2/build_companion.png new file mode 100644 index 000000000..6651768c6 Binary files /dev/null and b/docs/assets/images/build/win10_msys2/build_companion.png differ diff --git a/docs/assets/images/build/win10_msys2/build_full_simulator.png b/docs/assets/images/build/win10_msys2/build_full_simulator.png new file mode 100644 index 000000000..53c23ae17 Binary files /dev/null and b/docs/assets/images/build/win10_msys2/build_full_simulator.png differ diff --git a/docs/assets/images/build/win10_msys2/build_fw.png b/docs/assets/images/build/win10_msys2/build_fw.png new file mode 100644 index 000000000..2ad239f2c Binary files /dev/null and b/docs/assets/images/build/win10_msys2/build_fw.png differ diff --git a/docs/assets/images/build/win10_msys2/build_simulibTX16S.png b/docs/assets/images/build/win10_msys2/build_simulibTX16S.png new file mode 100644 index 000000000..5b140afc6 Binary files /dev/null and b/docs/assets/images/build/win10_msys2/build_simulibTX16S.png differ diff --git a/docs/assets/images/build/win10_msys2/companion.png b/docs/assets/images/build/win10_msys2/companion.png new file mode 100644 index 000000000..22f0677c9 Binary files /dev/null and b/docs/assets/images/build/win10_msys2/companion.png differ diff --git a/docs/assets/images/build/win10_msys2/fullsimulator_tx16s.png b/docs/assets/images/build/win10_msys2/fullsimulator_tx16s.png new file mode 100644 index 000000000..5a7096906 Binary files /dev/null and b/docs/assets/images/build/win10_msys2/fullsimulator_tx16s.png differ diff --git a/docs/assets/images/build/win10_msys2/installer.png b/docs/assets/images/build/win10_msys2/installer.png new file mode 100644 index 000000000..319af8575 Binary files /dev/null and b/docs/assets/images/build/win10_msys2/installer.png differ diff --git a/docs/assets/images/build/win10_msys2/msys2_build_scripted.png b/docs/assets/images/build/win10_msys2/msys2_build_scripted.png new file mode 100644 index 000000000..351ef27cd Binary files /dev/null and b/docs/assets/images/build/win10_msys2/msys2_build_scripted.png differ diff --git a/docs/assets/images/build/win10_msys2/msys2_mingw64_aqt.png b/docs/assets/images/build/win10_msys2/msys2_mingw64_aqt.png new file mode 100644 index 000000000..62a71dbf4 Binary files /dev/null and b/docs/assets/images/build/win10_msys2/msys2_mingw64_aqt.png differ diff --git a/docs/assets/images/build/win10_msys2/msys2_mingw64_pip.png b/docs/assets/images/build/win10_msys2/msys2_mingw64_pip.png new file mode 100644 index 000000000..fc6e3f2f6 Binary files /dev/null and b/docs/assets/images/build/win10_msys2/msys2_mingw64_pip.png differ diff --git a/docs/assets/images/build/win10_msys2/msys2_mingw64_wheel.png b/docs/assets/images/build/win10_msys2/msys2_mingw64_wheel.png new file mode 100644 index 000000000..e7d67b1e6 Binary files /dev/null and b/docs/assets/images/build/win10_msys2/msys2_mingw64_wheel.png differ diff --git a/docs/assets/images/build/win10_msys2/msys2_mingw_build_env1.png b/docs/assets/images/build/win10_msys2/msys2_mingw_build_env1.png new file mode 100644 index 000000000..9924c316b Binary files /dev/null and b/docs/assets/images/build/win10_msys2/msys2_mingw_build_env1.png differ diff --git a/docs/assets/images/build/win10_msys2/msys2_mingw_stage2.png b/docs/assets/images/build/win10_msys2/msys2_mingw_stage2.png new file mode 100644 index 000000000..7340b2beb Binary files /dev/null and b/docs/assets/images/build/win10_msys2/msys2_mingw_stage2.png differ diff --git a/docs/assets/images/build/win10_msys2/msys2_mingw_update1.png b/docs/assets/images/build/win10_msys2/msys2_mingw_update1.png new file mode 100644 index 000000000..4e777f7f7 Binary files /dev/null and b/docs/assets/images/build/win10_msys2/msys2_mingw_update1.png differ diff --git a/docs/assets/images/build/win10_msys2/msys2_mingw_update2.png b/docs/assets/images/build/win10_msys2/msys2_mingw_update2.png new file mode 100644 index 000000000..39b5f0db5 Binary files /dev/null and b/docs/assets/images/build/win10_msys2/msys2_mingw_update2.png differ diff --git a/docs/assets/images/build/win10_msys2/msys2_msys_install_pkgs.png b/docs/assets/images/build/win10_msys2/msys2_msys_install_pkgs.png new file mode 100644 index 000000000..36b25c6ff Binary files /dev/null and b/docs/assets/images/build/win10_msys2/msys2_msys_install_pkgs.png differ diff --git a/docs/assets/images/build/win10_msys2/msys2_msys_stage1.png b/docs/assets/images/build/win10_msys2/msys2_msys_stage1.png new file mode 100644 index 000000000..28c75ce80 Binary files /dev/null and b/docs/assets/images/build/win10_msys2/msys2_msys_stage1.png differ diff --git a/docs/assets/images/build/win10_msys2/msys2_pkgdb_update1.png b/docs/assets/images/build/win10_msys2/msys2_pkgdb_update1.png new file mode 100644 index 000000000..54c6f3a64 Binary files /dev/null and b/docs/assets/images/build/win10_msys2/msys2_pkgdb_update1.png differ diff --git a/docs/assets/images/build/win10_msys2/msys2_pkgdb_update2.png b/docs/assets/images/build/win10_msys2/msys2_pkgdb_update2.png new file mode 100644 index 000000000..8a1ee740f Binary files /dev/null and b/docs/assets/images/build/win10_msys2/msys2_pkgdb_update2.png differ diff --git a/docs/assets/images/build/win10_msys2/msys2_setup1.png b/docs/assets/images/build/win10_msys2/msys2_setup1.png new file mode 100644 index 000000000..0ca8159b7 Binary files /dev/null and b/docs/assets/images/build/win10_msys2/msys2_setup1.png differ diff --git a/docs/assets/images/build/win10_msys2/msys2_setup2.png b/docs/assets/images/build/win10_msys2/msys2_setup2.png new file mode 100644 index 000000000..87f552c44 Binary files /dev/null and b/docs/assets/images/build/win10_msys2/msys2_setup2.png differ diff --git a/docs/assets/images/build/win10_msys2/simu_start.png b/docs/assets/images/build/win10_msys2/simu_start.png new file mode 100644 index 000000000..685d8da27 Binary files /dev/null and b/docs/assets/images/build/win10_msys2/simu_start.png differ diff --git a/docs/assets/images/build/win10_msys2/vcppredistributable.png b/docs/assets/images/build/win10_msys2/vcppredistributable.png new file mode 100644 index 000000000..a15c476a1 Binary files /dev/null and b/docs/assets/images/build/win10_msys2/vcppredistributable.png differ diff --git a/docs/assets/images/flashing/STM32CubeProgrammer_01.png b/docs/assets/images/flashing/STM32CubeProgrammer_01.png new file mode 100644 index 000000000..df1a04277 Binary files /dev/null and b/docs/assets/images/flashing/STM32CubeProgrammer_01.png differ diff --git a/docs/assets/images/flashing/STM32CubeProgrammer_02.png b/docs/assets/images/flashing/STM32CubeProgrammer_02.png new file mode 100644 index 000000000..f036e89a4 Binary files /dev/null and b/docs/assets/images/flashing/STM32CubeProgrammer_02.png differ diff --git a/docs/assets/images/flashing/STM32CubeProgrammer_03.png b/docs/assets/images/flashing/STM32CubeProgrammer_03.png new file mode 100644 index 000000000..d5b381e91 Binary files /dev/null and b/docs/assets/images/flashing/STM32CubeProgrammer_03.png differ diff --git a/docs/assets/images/flashing/STM32CubeProgrammer_04.png b/docs/assets/images/flashing/STM32CubeProgrammer_04.png new file mode 100644 index 000000000..046bed0aa Binary files /dev/null and b/docs/assets/images/flashing/STM32CubeProgrammer_04.png differ diff --git a/docs/assets/images/flashing/STM32CubeProgrammer_05.png b/docs/assets/images/flashing/STM32CubeProgrammer_05.png new file mode 100644 index 000000000..38a872cd6 Binary files /dev/null and b/docs/assets/images/flashing/STM32CubeProgrammer_05.png differ diff --git a/docs/assets/images/flashing/STM32CubeProgrammer_06.png b/docs/assets/images/flashing/STM32CubeProgrammer_06.png new file mode 100644 index 000000000..1f26098ec Binary files /dev/null and b/docs/assets/images/flashing/STM32CubeProgrammer_06.png differ diff --git a/docs/assets/images/flashing/STM32CubeProgrammer_07.png b/docs/assets/images/flashing/STM32CubeProgrammer_07.png new file mode 100644 index 000000000..b87a458a4 Binary files /dev/null and b/docs/assets/images/flashing/STM32CubeProgrammer_07.png differ diff --git a/docs/assets/images/flashing/rcvr_yt_unbrick.jpg b/docs/assets/images/flashing/rcvr_yt_unbrick.jpg new file mode 100644 index 000000000..244dc01ab Binary files /dev/null and b/docs/assets/images/flashing/rcvr_yt_unbrick.jpg differ diff --git a/docs/assets/images/fs_fig1.png b/docs/assets/images/fs_fig1.png new file mode 100644 index 000000000..3add5b753 Binary files /dev/null and b/docs/assets/images/fs_fig1.png differ diff --git a/docs/assets/images/hw/flysky-mod/FlySky_Paladin_EV_gimbals_on_RM_TX16S.jpg b/docs/assets/images/hw/flysky-mod/FlySky_Paladin_EV_gimbals_on_RM_TX16S.jpg new file mode 100644 index 000000000..ec6d11539 Binary files /dev/null and b/docs/assets/images/hw/flysky-mod/FlySky_Paladin_EV_gimbals_on_RM_TX16S.jpg differ diff --git a/docs/assets/images/hw/flysky-mod/FlySky_Paladin_EV_gimbals_on_RM_TX16S_hookup.jpg b/docs/assets/images/hw/flysky-mod/FlySky_Paladin_EV_gimbals_on_RM_TX16S_hookup.jpg new file mode 100644 index 000000000..ef4398a96 Binary files /dev/null and b/docs/assets/images/hw/flysky-mod/FlySky_Paladin_EV_gimbals_on_RM_TX16S_hookup.jpg differ diff --git a/docs/assets/images/hw/flysky-mod/GimbalPlug.png b/docs/assets/images/hw/flysky-mod/GimbalPlug.png new file mode 100644 index 000000000..f742a133e Binary files /dev/null and b/docs/assets/images/hw/flysky-mod/GimbalPlug.png differ diff --git a/docs/assets/images/hw/flysky-mod/HawkRC_TX16S_adapter_set_step1.jpg b/docs/assets/images/hw/flysky-mod/HawkRC_TX16S_adapter_set_step1.jpg new file mode 100644 index 000000000..3073a8b00 Binary files /dev/null and b/docs/assets/images/hw/flysky-mod/HawkRC_TX16S_adapter_set_step1.jpg differ diff --git a/docs/assets/images/hw/flysky-mod/HawkRC_TX16S_adapter_set_step2.jpg b/docs/assets/images/hw/flysky-mod/HawkRC_TX16S_adapter_set_step2.jpg new file mode 100644 index 000000000..d1f60bdb9 Binary files /dev/null and b/docs/assets/images/hw/flysky-mod/HawkRC_TX16S_adapter_set_step2.jpg differ diff --git a/docs/assets/images/hw/flysky-mod/TX16S-Install.jpg b/docs/assets/images/hw/flysky-mod/TX16S-Install.jpg new file mode 100644 index 000000000..3f0e81519 Binary files /dev/null and b/docs/assets/images/hw/flysky-mod/TX16S-Install.jpg differ diff --git a/docs/assets/images/hw/flysky-mod/TX16S-Outlook.jpg b/docs/assets/images/hw/flysky-mod/TX16S-Outlook.jpg new file mode 100644 index 000000000..b1a96b384 Binary files /dev/null and b/docs/assets/images/hw/flysky-mod/TX16S-Outlook.jpg differ diff --git a/docs/assets/images/hw/flysky-mod/TX16S-PCBPlug.png b/docs/assets/images/hw/flysky-mod/TX16S-PCBPlug.png new file mode 100644 index 000000000..b6e76dc06 Binary files /dev/null and b/docs/assets/images/hw/flysky-mod/TX16S-PCBPlug.png differ diff --git a/docs/assets/images/hw/flysky-mod/TX16S_FlySky_gimbal_connection.jpg b/docs/assets/images/hw/flysky-mod/TX16S_FlySky_gimbal_connection.jpg new file mode 100644 index 000000000..fbc8fcbbb Binary files /dev/null and b/docs/assets/images/hw/flysky-mod/TX16S_FlySky_gimbal_connection.jpg differ diff --git a/docs/assets/images/hw/flysky-mod/TX16S_better_FlySky_gimbal_hookup.jpg b/docs/assets/images/hw/flysky-mod/TX16S_better_FlySky_gimbal_hookup.jpg new file mode 100644 index 000000000..975ea6f00 Binary files /dev/null and b/docs/assets/images/hw/flysky-mod/TX16S_better_FlySky_gimbal_hookup.jpg differ diff --git a/docs/assets/images/hw/flysky-pl18/background.png b/docs/assets/images/hw/flysky-pl18/background.png new file mode 100644 index 000000000..abf4003a4 Binary files /dev/null and b/docs/assets/images/hw/flysky-pl18/background.png differ diff --git a/docs/assets/images/hw/flysky-pl18/edgetx_bootloader_pl18.jpg b/docs/assets/images/hw/flysky-pl18/edgetx_bootloader_pl18.jpg new file mode 100644 index 000000000..1bd1bfce4 Binary files /dev/null and b/docs/assets/images/hw/flysky-pl18/edgetx_bootloader_pl18.jpg differ diff --git a/docs/assets/images/hw/flysky-pl18/edgetx_pl18ev.jpg b/docs/assets/images/hw/flysky-pl18/edgetx_pl18ev.jpg new file mode 100644 index 000000000..241471ddf Binary files /dev/null and b/docs/assets/images/hw/flysky-pl18/edgetx_pl18ev.jpg differ diff --git a/docs/assets/images/hw/flysky-pl18/pl18_bootloader_keys.jpg b/docs/assets/images/hw/flysky-pl18/pl18_bootloader_keys.jpg new file mode 100644 index 000000000..420c643c0 Binary files /dev/null and b/docs/assets/images/hw/flysky-pl18/pl18_bootloader_keys.jpg differ diff --git a/docs/assets/images/hw/flysky-pl18/pl18_hidden_buttons.jpg b/docs/assets/images/hw/flysky-pl18/pl18_hidden_buttons.jpg new file mode 100644 index 000000000..0f95fdfea Binary files /dev/null and b/docs/assets/images/hw/flysky-pl18/pl18_hidden_buttons.jpg differ diff --git a/docs/assets/images/hw/flysky-pl18/stm32cb_chipinfo.png b/docs/assets/images/hw/flysky-pl18/stm32cb_chipinfo.png new file mode 100644 index 000000000..73ee01e4f Binary files /dev/null and b/docs/assets/images/hw/flysky-pl18/stm32cb_chipinfo.png differ diff --git a/docs/assets/images/hw/flysky-pl18/stm32cb_connect.png b/docs/assets/images/hw/flysky-pl18/stm32cb_connect.png new file mode 100644 index 000000000..dd86b53dd Binary files /dev/null and b/docs/assets/images/hw/flysky-pl18/stm32cb_connect.png differ diff --git a/docs/assets/images/hw/flysky-pl18/stm32cb_read.png b/docs/assets/images/hw/flysky-pl18/stm32cb_read.png new file mode 100644 index 000000000..caf8bb091 Binary files /dev/null and b/docs/assets/images/hw/flysky-pl18/stm32cb_read.png differ diff --git a/docs/assets/images/hw/flysky-pl18/stm32cb_saveas.png b/docs/assets/images/hw/flysky-pl18/stm32cb_saveas.png new file mode 100644 index 000000000..57f39a45a Binary files /dev/null and b/docs/assets/images/hw/flysky-pl18/stm32cb_saveas.png differ diff --git a/docs/assets/images/mixersync.png b/docs/assets/images/mixersync.png new file mode 100644 index 000000000..6aabb8b74 Binary files /dev/null and b/docs/assets/images/mixersync.png differ diff --git a/docs/assets/stylesheets/extra.css b/docs/assets/stylesheets/extra.css new file mode 100644 index 000000000..861e10efd --- /dev/null +++ b/docs/assets/stylesheets/extra.css @@ -0,0 +1,12 @@ +:root { + --md-primary-fg-color: #0C7BCD; + --md-primary-fg-color--light: #0C7BCD; + --md-primary-fg-color--dark: #0C7BCD; +} + +.md-header__button.md-logo img,.md-header__button.md-logo svg { + fill: currentcolor; + display: block; + height: 3rem; + width: auto +} diff --git a/docs/building/codespaces.md b/docs/building/codespaces.md new file mode 100644 index 000000000..47813eccf --- /dev/null +++ b/docs/building/codespaces.md @@ -0,0 +1,71 @@ +# Building in a Web Browser with GitHub CodeSpaces + +An easy option to build EdgeTX radio firmwares without having to set up a local build environment on your own computer, is provided by GitHub CodeSpaces. The only requirement is that you have an account at [GitHub](https://github.com/). + +# Preparation + +To start building EdgeTX firmware for your radio, open the following link with the web browser of your choice: + +https://codespaces.new/EdgeTX/edgetx + +and you should be greeted with a screen similar to the following. If you don't want to build from the main development branch (i.e. you want to build a from a stable release), you can change to a different branch, i.e. 2.11 (at 1). If you want builds to run faster, you can also change the machine type to one with more CPUs and RAM (at 2), but please note this will reduce the amount of free time you have for using GitHub Codespaces (120 hrs per month for 2 CPU machine). + +image + +After a brief wait, you should be greeted with a Visual Studio Code like development environment in a browser with EdgeTX source code tree preloaded from GitHub. It may still take a few minutes to load the first time, as it prepares the build environment. You should see something similar to this at the bottom right while this is underway: + +image + +Once it has completed, you should have a screen similar to this. The file browser (at 1) of the left will let you navigate the file system, and also download your compiled firmware (as described later). The buttons at the top right (at 2) let you turn the various side panels on and off - I would suggest you turn off the right sidebar as it is just cluttering the place. The section at the bottom (at 3) is the terminal, which you will need in order to run the various compile commands that follow. + +image + +As part of preparing the build environment, it should have initialised all the submodules needed to build the firmware for you. If for some reason this hasn't happened, run `git submodule update --init --recursive` at the terminal. + +# Building firmware + +Firstly, change to (and create if it does not exist) a build directory: +``` +mkdir -p build && cd build +``` + +The next step is to tell the development system for which radio and with which configuration option you would like the firmware to be built. You do this by entering a _cmake_ command in the terminal section of the Visual Studio Code window (bottom right pane; feel free to close all the popups if they come on top). Here for example: + +``` +cmake -Wno-dev -DPCB=X10 -DPCBREV=TX16S -DBLUETOOTH=YES -DCMAKE_BUILD_TYPE=Release ../ +``` + +we instruct the CMake system to create makefiles for building for the RadioMaster TX16S (PCB=X10, PCBREV=TX16S), enable Bluetooth support (BLUETOOTH=YES) and selected the type as a Release build without debug symbols included (CMAKE_BUILD_TYPE=Release). +(If you are curious about the options available, enter the following command in terminal to list all options: `cmake -LAH ../` ) + +Next, issue: +``` +cmake --build . --target arm-none-eabi-configure --parallel 2 +``` + +> [!NOTE] +> The `--parallel 2` in the command above instructs the cmake build system as to how many tasks to execute in parallel. Typically, you would set this to the number of CPU cores your machine has. So if you are using a higher CPU core count GitHub machine type, you can increase this to suit, and get a faster build. + +Only a few seconds later, you should be greeted with "-- Generating done" message. + +If so, enter again in terminal the following line to start the compilation and linking step and press Enter: +``` +cmake --build arm-none-eabi --target firmware +``` + +This time it can take few minutes so until the firmware binary is successfully built. If you see "[100%] Built target firmware" then all went smoothly, and you have just made yourself a custom EdgeTX firmware. If you are making incremental modifications to the firmware, subsequent firmware builds will be a lot faster. + +> [!TIP] +> If you want more information about the firmware binary - such as how big the firmware is in relation to the FLASH memory the target handset has, you can compile the `firmware-size` target instead of firmware, and you'll get a summary at the end of the firmware build. + +It's a good idea to rename the binary, so that it is easier later to see the target radio and which options were baked into it. For this, issue in the terminal: +``` +cd arm-none-eabi +mv firmware.bin edgetx_main_tx16s_bt_release.bin +``` + +In the left file browser tree open the **build** folder and then open **arm-none-eabi** folder. Right click at _edgetx_main_tx16s_bt_release.bin_ and select Download. + +Put the downloaded firmware binary into your radio SD card \FIRMWARE subfolder, and flash it to your radio either using EdgeTX bootloader, [EdgeTX Buddy](https://buddy.edgetx.org/), EdgeTX Companion or [STM32CubeProgrammer](../mods/unbrick.md). + +Use [EdgeTX Buddy](https://buddy.edgetx.org/) or EdgeTX Companion to fill your SD card appropriately for your radio. diff --git a/docs/building/compilation-options.md b/docs/building/compilation-options.md new file mode 100644 index 000000000..80dc60329 --- /dev/null +++ b/docs/building/compilation-options.md @@ -0,0 +1,302 @@ +# Compilation Options + +!!! note "Work in Progress" + This page is a work in progress. The raw option list below is an initial dump of all compile-time defines. It still needs to be sorted into categories, have details added for options like `PCBREV` (with all possible values), and be converted into tables. + + **TODO:** + - [ ] Sort into categories — PCB/TX model, hardware-specific, handy default setting flags, etc. + - [ ] Add details for options like `PCBREV` with all possible values + - [ ] Convert to a set of tables + - [x] Clear out system-specific / autogenerated flags + +Initial dump of all the compile time defines / options (`cmake -LAH` output) + +``` +// Support for AFHDS2 +AFHDS2:BOOL=OFF + +// Support for AFHDS3 +AFHDS3:BOOL=ON + +// Allow nightly builds download / update +ALLOW_NIGHTLY_BUILDS:BOOL=OFF + +// Enable asterisk icon (test only firmware) +ASTERISK:BOOL=OFF + +// Automatic source detection in menus +AUTOSOURCE:BOOL=ON + +// Automatic switch detection in menus +AUTOSWITCH:BOOL=ON + +// Support for bluetooth module +BLUETOOTH:BOOL=OFF + +// Include Bootloader +BOOTLOADER:BOOL=ON + +// Command Line Interface +CLI:BOOL=OFF + +// Crossfire TX Module +CROSSFIRE:BOOL=ON + +// Curves +CURVES:BOOL=ON + +// Dangerous module functions (RangeCheck / Bind / Module OFF, etc.) available +DANGEROUS_MODULE_FUNCTIONS:BOOL=OFF + +// Double Keys +DBLKEYS:BOOL=ON + +// Debug mode +DEBUG:BOOL=Y + +// Count interrupts +DEBUG_INTERRUPTS:BOOL=OFF + +// Debug latency +DEBUG_LATENCY:BOOL=OFF + +// Turn on debug output for storage import +DEBUG_STORAGE_IMPORT:BOOL=OFF + +// Task switching statistics +DEBUG_TASKS:BOOL=OFF + +// Time critical parts of the code +DEBUG_TIMERS:BOOL=OFF + +// Debug Trace Screen +DEBUG_TRACE_BUFFER:BOOL=OFF + +// Count individual USB interrupts +DEBUG_USB_INTERRUPTS:BOOL=OFF + +// Turn on windows traces +DEBUG_WINDOWS:BOOL=OFF + +// Default sticks mode +DEFAULT_MODE:STRING= + +// +DEFAULT_TEMPLATE_SETUP:STRING=21 + +// Disable building companion and simulators +DISABLE_COMPANION:BOOL=OFF + +// Enable SD card disk cache +DISK_CACHE:BOOL=ON + +// DSM2 TX Module +DSM2:BOOL=ON + +// Competition mode (no telemetry) +FAI:BOOL=OFF + +// Support of old FAS prototypes (different resistors) +FAS_PROTOTYPE:BOOL=OFF + +// Configure Firmware target (can be turned off for compiling Companion only) +FIRMWARE_TARGET:BOOL=ON + +// Flight Modes +FLIGHT_MODES:BOOL=ON + +// Enable FlySky Hall Sticks +FLYSKY_HALL_STICKS:BOOL=OFF + +// Used to build FrSky released firmware +FRSKY_RELEASE:BOOL=OFF + +// Reverse sticks for FrSky sticks +FRSKY_STICKS:BOOL=OFF + +// Ghost TX Module +GHOST:BOOL=ON + +// GUI enabled +GUI:BOOL=ON + +// Global variables +GVARS:BOOL=ON + +// Support for R9M 2019 hardware mod +HARDWARE_EXTERNAL_ACCESS_MOD:BOOL=OFF + +// Allow multi trainer +HARDWARE_TRAINER_MULTI:BOOL=OFF + +// Heli menu +HELI:BOOL=ON + +// Used to build IMRC released firmware +IMRC_RELEASE:BOOL=OFF + +// Support for internal ublox GPS +INTERNAL_GPS:BOOL=YES + +// Baud rate for internal GPS +INTERNAL_GPS_BAUDRATE:STRING=9600 + +// Support for MULTI internal module +INTERNAL_MODULE_MULTI:BOOL=ON + +// Enable ADC jitter measurement +JITTER_MEASURE:BOOL=OFF + +// Bluetooth Logs on SD card +LOG_BLUETOOTH:BOOL=OFF + +// Telemetry Logs on SD card +LOG_TELEMETRY:BOOL=OFF + +// Enable LUA support +LUA:BOOL=ON + +// Trace Lua memory (de)allocations to debug port (also needs DEBUG=YES NANO=NO) +LUA_ALLOCATOR_TRACER:BOOL=OFF + +// Pre-compile and save Lua scripts +LUA_COMPILER:BOOL=ON + +// Script loading mode and compilation flags [btTxcd] (see loadScript() API docs). Blank for default ('bt' on radio, 'T' on SIMU/DEBUG builds) +LUA_SCRIPT_LOAD_MODE:STRING= + +// Add support for D8 modules +MODULE_PROTOCOL_D8:BOOL=ON + +// Add support for FCC modules +MODULE_PROTOCOL_FCC:BOOL=ON + +// Add support for non certified FLEX modules +MODULE_PROTOCOL_FLEX:BOOL=OFF + +// Add support for EU/LBT modules +MODULE_PROTOCOL_LBT:BOOL=ON + +// Standard size TX Module +MODULE_SIZE_STD:BOOL=ON + +// DIY Multiprotocol TX Module (https://github.com/pascallanger/DIY-Multiprotocol-TX-Module) +MULTIMODULE:BOOL=ON + +// Use nano newlib and binalloc +NANO:BOOL=OFF + +// OverrideChannel function available +OVERRIDE_CHANNEL_FUNCTION:BOOL=ON + +// Radio type, one of: X9LITE;X9LITES;X7;XLITE;XLITES;X9D;X9D+;X9E;X10;X12S;SKY9X;9XRPRO;AR9X;NV14 +PCB:STRING=X10 + +// PCB Revision +PCBREV:STRING=TX16S + +// Popup level +POPUP_LEVEL:STRING=2 + +// PPM TX Module +PPM:BOOL=ON + +// PPM center adjustable +PPM_CENTER_ADJUSTABLE:BOOL=ON + +// PPM limits symetrical +PPM_LIMITS_SYMETRICAL:BOOL=OFF + +// PPM display unit (US/PERCENT_PREC1/PERCENT_PREC0) +PPM_UNIT:STRING=PERCENT_PREC1 + +// Pwr button type (PRESS/SWITCH) +PWR_BUTTON:STRING=PRESS + +// PXX1 protocol support +PXX1:BOOL=ON + +// PXX2 protocol support +PXX2:BOOL=OFF + +// RAS (SWR) enabled +RAS:BOOL=ON + +// SBUS TX Module +SBUS:BOOL=ON + +// Enable debugger semihosting +SEMIHOSTING:BOOL=OFF + +// Alternative simulator library search path +SIMULATOR_INSTALL_PREFIX:STRING= + +// Enable disk IO simulation in simulator. Simulator will use FatFs module and simulated IO layer that uses "./sdcard.image" file as image of SD card. This file must contain whole SD card from first to last sector +SIMU_DISKIO:BOOL=OFF + +// Pre-compile and save Lua scripts in simulator. +SIMU_LUA_COMPILER:BOOL=ON + +// Configure libsimulator/simu targets (can be turned off for compiling Companion only) +SIMU_TARGET:BOOL=ON + +// Splash (DEFAULT/OFF/FRSKY) +SPLASH:STRING=DEFAULT + +// Use QTableWidget for grid layouts +TABLE_LAYOUT:BOOL=OFF + +// Used to build TBS released firmware +TBS_RELEASE:BOOL=OFF + +// Model templates menu +TEMPLATES:BOOL=OFF + +// Warn this is a test build +TEST_BUILD_WARNING:BOOL=OFF + +// Timers count (2 or 3) +TIMERS:STRING=3 + +// Traces audio enabled +TRACE_AUDIO:BOOL=OFF + +// Traces FatFS enabled +TRACE_FATFS:BOOL=OFF + +// Turn on traces for Lua internals +TRACE_LUA_INTERNALS:BOOL=OFF + +// Traces SD enabled +TRACE_SD_CARD:BOOL=OFF + +// Turn on traces in simpgmspace.cpp +TRACE_SIMPGMSPACE:BOOL=ON + +// Radio language, one of: CZ;DE;EN;ES;FR;IT;PT;SK;SE;PL;HU;NL;CN;TW +TRANSLATIONS:STRING=EN + +// Enable the Unexpected Shutdown screen +UNEXPECTED_SHUTDOWN:BOOL=ON + +// Enable USB serial (CDC) +USB_SERIAL:BOOL=ON + +// Show extra information while processing CMakeLists.txt files. +VERBOSE_CMAKELISTS:BOOL=OFF + +// Treat any compiler warning as an error (adds -Werror flag). +WARNINGS_AS_ERRORS:BOOL=OFF + +// Enable hardware Watchdog +WATCHDOG:BOOL=ON + +// Draw bounding boxes around windows +WINDOWS_INSPECT_BORDERS:BOOL=OFF + +// XJT TX Module +XJT:BOOL=ON + +// Enable YAML storage +YAML_STORAGE:BOOL=OFF +``` diff --git a/docs/building/index.md b/docs/building/index.md new file mode 100644 index 000000000..589c4d761 --- /dev/null +++ b/docs/building/index.md @@ -0,0 +1,25 @@ +# Building EdgeTX + +This section contains step-by-step build instructions for every supported platform. Whether you want to build a custom firmware binary, run the EdgeTX simulator, or contribute to development, pick the guide that matches your environment. + +## Available build guides + +| Guide | Platform | +|---|---| +| [In a Web Browser (CodeSpaces)](codespaces.md) | Any OS — no local setup required | +| [Windows](windows.md) | Windows — Visual Studio 2022 + Ninja | +| [Windows (Docker)](windows-docker.md) | Windows 10 — Docker Desktop | +| [Linux (Ubuntu 22.04)](linux-ubuntu-22.04.md) | Ubuntu 22.04 (bare-metal, VM, or WSL2) | +| [Linux (Ubuntu 24.04)](linux-ubuntu-24.04.md) | Ubuntu 24.04 (bare-metal, VM, or WSL2) | +| [Linux (WSL / Ubuntu 20.04)](linux-wsl.md) | Windows 10/11 — WSL2 with Ubuntu 20.04 | +| [macOS (Sequoia / Tahoe)](macos-sequoia.md) | macOS 15 (Sequoia) and macOS 26 (Tahoe) | +| [macOS (Sonoma)](macos-sonoma.md) | macOS 14.1 (Sonoma) | +| [macOS (Catalina)](macos-catalina.md) | macOS 10.15 (Catalina) | +| [Compilation Options](compilation-options.md) | Reference list of all CMake build flags | +| [Qt Creator (Obsolete)](qt-creator.md) | Historical — no longer maintained | + +## Notes + +- The document here is meant to help you develop or test changes to EdgeTX on your PC, not to build flight/radio safe version of binaries. +- For a list of all available CMake build options, see [Compilation Options](compilation-options.md). +- For radio-specific build flags (`PCB`, `PCBREV`), refer to the build scripts at [https://github.com/EdgeTX/edgetx/tree/main/tools](https://github.com/EdgeTX/edgetx/tree/main/tools). diff --git a/docs/building/linux-ubuntu-22.04.md b/docs/building/linux-ubuntu-22.04.md new file mode 100644 index 000000000..1f6d0b927 --- /dev/null +++ b/docs/building/linux-ubuntu-22.04.md @@ -0,0 +1,121 @@ +# Build Instructions under Ubuntu 22.04 + +The document here is meant to help you develop or test changes to EdgeTX on your PC, not to build flight/radio safe version of binaries. + +- [Setting up the build environment for EdgeTX](#setting-up-the-build-environment-for-edgetx) +- [Building EdgeTX firmware for the radio](#building-edgetx-firmware-for-the-radio) +- [Building Companion, Simulator and radio simulator libraries](#building-companion-simulator-and-radio-simulator-libraries) + +## Setting up the build environment for EdgeTX + +You can setup Ubuntu 22.04 on bare-metal, inside a virtual machine environment, or using WSL2 under Windows 10. For WSL2 installation, please see a dedicated page about it: [Setting up Ubuntu 20.04 in a Windows Subsystem for Linux](linux-wsl.md). + +* Download [Ubuntu 22.04](https://ubuntu.com/download/desktop) and install it (using Minimal installation type is sufficient. Allow _Download updates while installing Ubuntu_. 3rd party software is not required, unless you need this for graphics or WiFi adapter on your PC). +* When the installer has finished and the obligatory reboot is done, log in. Install updates using Software Updater (click _Activities_ in top left corner, type in _Software Updater_ and press _Enter_). **Restart** the PC and log in again after reboot. +* To make setting up the build environment as easy as possible, we created a shell script that includes all the necessary commands. In the next steps, we download it, make it executable and run it. Active Internet connection is required for the script to be able to download the required packages for installation. Start, by opening a terminal window (click _Activities_ in the top left corner, type _terminal_ and press _Enter_). Enter the following 3 lines, each line at a time and enter your password (with sudo rights) if asked: +``` +wget https://raw.githubusercontent.com/EdgeTX/edgetx/main/tools/setup_buildenv_ubuntu22.04.sh +``` +``` +chmod a+x setup_buildenv_ubuntu22.04.sh +``` +``` +./setup_buildenv_ubuntu22.04.sh +``` +* If all went smoothly, you should not have seen any errors. + +If you are interested to see what the script does or which functions it calls, you can open it in a text editor and have look at it - it's pretty self-explanatory (_gedit_ for example in Ubuntu is a text editor with syntax highlighting). You can alternatively start the script with _--pause_ argument to stop the script execution after each step to better inspect the output. To achieve this, issue `./setup_buildenv_ubuntu22.04.sh --pause` as the last command in the above list instead. + +It's best to reboot the PC before continuing to next steps. This concludes the build setup preparations. + +## Building EdgeTX firmware for the radio + +For tidy files and folder hierarchy, it's best to create a dedicated subfolder in the current user home for EdgeTX, as a container for various EdgeTX flavors and builds. In the terminal window, issue the following commands, one at a time: +``` +mkdir ~/edgetx +``` +``` +cd ~/edgetx +``` + +We will next fetch the EdgeTX source files from the GitHub main development branch into local subfolder /edgetx/edgetx_main in current user home, prepare the environment and build output directory. Issue, in the same terminal window as above, the following commands, one at a time: +``` +git clone --recursive -b main https://github.com/EdgeTX/edgetx.git edgetx_main +``` +``` +cd edgetx_main && mkdir build-output && cd build-output +``` + +To build EdgeTX, we need to minimally specify the radio target, but can further select or de-select a number of build-time options. The following command will create a text-file list of all options for you to look at and saves it in current user home directory: +``` +cmake -LAH ../ > ~/edgetx_main-cmake-options.txt +``` + +You can use, e.g. _gedit_ under Ubuntu to view the file. + +As an example, we will build next for RadioMaster TX16S (PCB=X10, PCBREV=TX16S), mode 2 default stick (DEFAULT_MODE=2), global variables enabled (GVARS=YES), servo output unit as microseconds (PPM_UNIT=US), include Lua mixer script support (LUA_MIXER=YES) and selected the type as a Debug build with debug symbols included (CMAKE_BUILD_TYPE=Debug). The CMake command for this is (issue the following without line breaks and be sure to include at the end the two dots and a slash exactly as here listed): +``` +cmake -DPCB=X10 -DPCBREV=TX16S -DDEFAULT_MODE=2 -DGVARS=YES -DPPM_UNIT=US -DLUA_MIXER=YES -DCMAKE_BUILD_TYPE=Debug ../ +``` +If you do not want to include the debug symbols, use `-DCMAKE_BUILD_TYPE=Release` instead. + +To build for other radios, you just need to select another build target by specifying appropriate values for `PCB` and `PCBREV` for your radio. If you are are wanting to build for multiple different targets, it is best to use a different build folder for each. Otherwise, delete the `CMakeCache.txt` file from the build directory before before running `cmake` to configure a different transmitter build, otherwise cached configuration values from your previous build target will cause weird compile results. As a tip, which values to use, have a look at a Python script according to your radio manufacturer in a file named `build-.py` under [https://github.com/EdgeTX/edgetx/tree/main/tools](https://github.com/EdgeTX/edgetx/tree/main/tools) + +Starting with 2.8, an additional step is required. Issue: +``` +make configure +``` +Alternatively, you can issue `make arm-none-eabi-configure` if you only want to build radio firmware or `make native-configure` if you only want to build targets meant to be run on computer (running `make configure` activates both architecture targets). + +Only a few seconds later, you should be greeted with "-- Generating done" message. + +The configure process generates the _makefile_ that is required in the next step to build the firmware. For this, issue: +``` +make -j`nproc` firmware +``` +This process can take some minutes to complete (the parameter -j'nproc' instructs the make to use as many parallel threads as the current system has CPU cores. This speeds up the build quite significantly). +If successful, you should find a firmware binary _firmware.bin_ in the current folder, that you can flash into your radio. + +It's a good idea to rename the binary, so that it is easier later to see the target radio and which options were baked into it. For this, issue in the build folder, e.g.: +``` +cd arm-none-eabi +mv firmware.bin edgetx_main_tx16s_lua-ppmus-mode2_debug.bin +``` + +You will need to prepare a clean microSD card and fill it with the content according to your radio type from [https://github.com/EdgeTX/edgetx-sdcard/releases/tag/latest](https://github.com/EdgeTX/edgetx-sdcard/releases/tag/latest) + +The following page lists which zip file you need: [https://github.com/EdgeTX/edgetx-sdcard](https://github.com/EdgeTX/edgetx-sdcard) + +You can use [OpenTX Companion](https://www.open-tx.org/downloads.html) or [STM32CubeProgrammer](https://www.st.com/en/development-tools/stm32cubeprog.html) to flash the binary to your radio. For further instructions, see: +[https://github.com/EdgeTX/edgetx.github.io/wiki/How-to-install-EdgeTX--(pre-release)-for-the-first-time](https://github.com/EdgeTX/edgetx.github.io/wiki/How-to-install-EdgeTX--(pre-release)-for-the-first-time) + +## Building Companion, Simulator and radio simulator libraries + +To build radio simulator library, issue in the same terminal as opened previously: +``` +make -j`nproc` libsimulator +``` + +From EdgeTX 2.10 onwards, Companion and Simulator only incorporate hardware definitions for radio simulated libraries built before they themselves are built. + +In order to build for other radio target, you need to re-run the `cmake` line above, with other `PCB` and `PCBREV` tags. + +After building all required radio simulator libraries, build the EdgeTX Companion binary, issue in the same terminal as opened previously: +``` +make -j`nproc` companion +``` +To launch Companion, change into `native` directory and issue: `./companion` +where `` is EdgeTX version string in format of two digits. For example, for EdgeTX 2.9 use 29, thus `companion29`, for 2.10 `companion210` and so on. + +To build EdgeTX Simulator binary, issue: +``` +make -j`nproc` simulator +``` + +Before you run the simulator, copy the SD card content according to your radio target from [https://github.com/EdgeTX/edgetx-sdcard/releases/tag/latest](https://github.com/EdgeTX/edgetx-sdcard/releases/tag/latest) to your system and extract it e.g. to `~/edgetx/simu_sdcard/horus` + +Also, you should create a radio profile first with `./companion`, before you can successfully run the full simulator. + +To launch the simulator, change into `native` directory and issue: `./simulator`. In the dialog that pops up, select _SD Path_ as data source and under _SD Image Path:_ browse to `~/edgetx/simu_sdcard/horus` + +[![EdgeTX simulator on Linux](../assets/images/build/linux/EdgeTX_simulator_Linux.png)](../assets/images/build/linux/EdgeTX_simulator_Linux.png) diff --git a/docs/building/linux-ubuntu-24.04.md b/docs/building/linux-ubuntu-24.04.md new file mode 100644 index 000000000..0f047a7c7 --- /dev/null +++ b/docs/building/linux-ubuntu-24.04.md @@ -0,0 +1,121 @@ +# Build Instructions under Ubuntu 24.04 + +The document here is meant to help you develop or test changes to EdgeTX on your PC, not to build flight/radio safe version of binaries. + +- [Setting up the build environment for EdgeTX](#setting-up-the-build-environment-for-edgetx) +- [Building EdgeTX firmware for the radio](#building-edgetx-firmware-for-the-radio) +- [Building Companion, Simulator and radio simulator libraries](#building-companion-simulator-and-radio-simulator-libraries) + +## Setting up the build environment for EdgeTX + +You can setup Ubuntu 24.04 on bare-metal, inside a virtual machine environment, or using WSL2 under Windows 10. For WSL2 installation, please see a dedicated page about it: [Setting up Ubuntu 20.04 in a Windows Subsystem for Linux](linux-wsl.md). + +* Download [Ubuntu 24.04](https://ubuntu.com/download/desktop) and install it (using Minimal installation type is sufficient. Allow _Download updates while installing Ubuntu_. 3rd party software is not required, unless you need this for graphics or WiFi adapter on your PC). +* When the installer has finished and the obligatory reboot is done, log in. Install updates using Software Updater (click _Activities_ in top left corner, type in _Software Updater_ and press _Enter_). **Restart** the PC and log in again after reboot. +* To make setting up the build environment as easy as possible, we created a shell script that includes all the necessary commands. In the next steps, we download it, make it executable and run it. Active Internet connection is required for the script to be able to download the required packages for installation. Start, by opening a terminal window (click _Activities_ in the top left corner, type _terminal_ and press _Enter_). Enter the following 3 lines, each line at a time and enter your password (with sudo rights) if asked: +``` +wget https://raw.githubusercontent.com/EdgeTX/edgetx/main/tools/setup_buildenv_ubuntu24.04.sh +``` +``` +chmod a+x setup_buildenv_ubuntu24.04.sh +``` +``` +./setup_buildenv_ubuntu24.04.sh +``` +* If all went smoothly, you should not have seen any errors. + +If you are interested to see what the script does or which functions it calls, you can open it in a text editor and have look at it - it's pretty self-explanatory (_gedit_ for example in Ubuntu is a text editor with syntax highlighting). You can alternatively start the script with _--pause_ argument to stop the script execution after each step to better inspect the output. To achieve this, issue `./setup_buildenv_ubuntu24.04.sh --pause` as the last command in the above list instead. + +It's best to reboot the PC before continuing to next steps. This concludes the build setup preparations. + +## Building EdgeTX firmware for the radio + +For tidy files and folder hierarchy, it's best to create a dedicated subfolder in the current user home for EdgeTX, as a container for various EdgeTX flavors and builds. In the terminal window, issue the following commands, one at a time: +``` +mkdir ~/edgetx +``` +``` +cd ~/edgetx +``` + +We will next fetch the EdgeTX source files from the GitHub main development branch into local subfolder /edgetx/edgetx_main in current user home, prepare the environment and build output directory. Issue, in the same terminal window as above, the following commands, one at a time: +``` +git clone --recursive -b main https://github.com/EdgeTX/edgetx.git edgetx_main +``` +``` +cd edgetx_main && mkdir build-output && cd build-output +``` + +To build EdgeTX, we need to minimally specify the radio target, but can further select or de-select a number of build-time options. The following command will create a text-file list of all options for you to look at and saves it in current user home directory: +``` +cmake -LAH ../ > ~/edgetx_main-cmake-options.txt +``` + +You can use, e.g. _gedit_ under Ubuntu to view the file. + +As an example, we will build next for RadioMaster TX16S (PCB=X10, PCBREV=TX16S), mode 2 default stick (DEFAULT_MODE=2), global variables enabled (GVARS=YES), servo output unit as microseconds (PPM_UNIT=US), include Lua mixer script support (LUA_MIXER=YES) and selected the type as a Debug build with debug symbols included (CMAKE_BUILD_TYPE=Debug). The CMake command for this is (issue the following without line breaks and be sure to include at the end the two dots and a slash exactly as here listed): +``` +cmake -DPCB=X10 -DPCBREV=TX16S -DDEFAULT_MODE=2 -DGVARS=YES -DPPM_UNIT=US -DLUA_MIXER=YES -DCMAKE_BUILD_TYPE=Debug ../ +``` +If you do not want to include the debug symbols, use `-DCMAKE_BUILD_TYPE=Release` instead. + +To build for other radios, you just need to select another build target by specifying appropriate values for `PCB` and `PCBREV` for your radio. If you are are wanting to build for multiple different targets, it is best to use a different build folder for each. Otherwise, delete the `CMakeCache.txt` file from the build directory before before running `cmake` to configure a different transmitter build, otherwise cached configuration values from your previous build target will cause weird compile results. As a tip, which values to use, have a look at a Python script according to your radio manufacturer in a file named `build-.py` under [https://github.com/EdgeTX/edgetx/tree/main/tools](https://github.com/EdgeTX/edgetx/tree/main/tools) + +Starting with 2.8, an additional step is required. Issue: +``` +make configure +``` +Alternatively, you can issue `make arm-none-eabi-configure` if you only want to build radio firmware or `make native-configure` if you only want to build targets meant to be run on computer (running `make configure` activates both architecture targets). + +Only a few seconds later, you should be greeted with "-- Generating done" message. + +The configure process generates the _makefile_ that is required in the next step to build the firmware. For this, issue: +``` +make -j`nproc` firmware +``` +This process can take some minutes to complete (the parameter -j'nproc' instructs the make to use as many parallel threads as the current system has CPU cores. This speeds up the build quite significantly). +If successful, you should find a firmware binary _firmware.bin_ in the current folder, that you can flash into your radio. + +It's a good idea to rename the binary, so that it is easier later to see the target radio and which options were baked into it. For this, issue in the build folder, e.g.: +``` +cd arm-none-eabi +mv firmware.bin edgetx_main_tx16s_lua-ppmus-mode2_debug.bin +``` + +You will need to prepare a clean microSD card and fill it with the content according to your radio type from [https://github.com/EdgeTX/edgetx-sdcard/releases/tag/latest](https://github.com/EdgeTX/edgetx-sdcard/releases/tag/latest) + +The following page lists which zip file you need: [https://github.com/EdgeTX/edgetx-sdcard](https://github.com/EdgeTX/edgetx-sdcard) + +You can use [OpenTX Companion](https://www.open-tx.org/downloads.html) or [STM32CubeProgrammer](https://www.st.com/en/development-tools/stm32cubeprog.html) to flash the binary to your radio. For further instructions, see: +[https://github.com/EdgeTX/edgetx.github.io/wiki/How-to-install-EdgeTX--(pre-release)-for-the-first-time](https://github.com/EdgeTX/edgetx.github.io/wiki/How-to-install-EdgeTX--(pre-release)-for-the-first-time) + +## Building Companion, Simulator and radio simulator libraries + +To build radio simulator library, issue in the same terminal as opened previously: +``` +make -j`nproc` libsimulator +``` + +From EdgeTX 2.10 onwards, Companion and Simulator only incorporate hardware definitions for radio simulated libraries built before they themselves are built. + +In order to build for other radio target, you need to re-run the `cmake` line above, with other `PCB` and `PCBREV` tags. + +After building all required radio simulator libraries, build the EdgeTX Companion binary, issue in the same terminal as opened previously: +``` +make -j`nproc` companion +``` +To launch Companion, change into `native` directory and issue: `./companion` +where `` is EdgeTX version string in format of two digits. For example, for EdgeTX 2.9 use 29, thus `companion29`, for 2.10 `companion210` and so on. + +To build EdgeTX Simulator binary, issue: +``` +make -j`nproc` simulator +``` + +Before you run the simulator, copy the SD card content according to your radio target from [https://github.com/EdgeTX/edgetx-sdcard/releases/tag/latest](https://github.com/EdgeTX/edgetx-sdcard/releases/tag/latest) to your system and extract it e.g. to `~/edgetx/simu_sdcard/horus` + +Also, you should create a radio profile first with `./companion`, before you can successfully run the full simulator. + +To launch the simulator, change into `native` directory and issue: `./simulator`. In the dialog that pops up, select _SD Path_ as data source and under _SD Image Path:_ browse to `~/edgetx/simu_sdcard/horus` + +[![EdgeTX simulator on Linux](../assets/images/build/linux/EdgeTX_simulator_Linux.png)](../assets/images/build/linux/EdgeTX_simulator_Linux.png) diff --git a/docs/building/linux-wsl.md b/docs/building/linux-wsl.md new file mode 100644 index 000000000..c7ec420f1 --- /dev/null +++ b/docs/building/linux-wsl.md @@ -0,0 +1,135 @@ +# Setting up Ubuntu 20.04 in a Windows Subsystem for Linux + +# For who is this guide? + +This guide is especially useful for people who want to help testing firmware and or LUA scripts. It will allow to run a simple simulator with the LUA debug and all other radio functions on your W10 64-bit computer in a separate window, running Ubuntu. + +# How does this work + +Windows 10 / Windows 11 is now able to run another OS (Linux) in a subsystem. However, this subsystem does not have access to the screen as it is shipped. By default, at the time of writing (as it will change in the near future with WSLg) it only offers a terminal interface. By using an X window server (in this guide we use VcXsrv) a window can be created to which the subsystem can connect to output graphical content. This can be used to be used to run the radio simulator in. We will install Ubuntu on the subsystem, so we are ready to use all the build tools already supported. + +# Installation procedure + +We are going to install the following things: + +* WSL2 (Windows Subsystem for Linux, version 2) +* A Linux distribution (Ubuntu 20.04 LTS) +* Setup the EdgeTX build environment in order to be able to compile firmware and simulators +* Setup the X-Windows server (VcXserver) so that we can run graphical programs like the simulator + +## WSL2 installation + +You can use the [guide from Microsoft](https://docs.microsoft.com/en-us/windows/wsl/install-win10). It is really straightforward. The steps for the manual install are below: + +* In the search box in the Windows taskbar (or press Window(KEY)+R) type "powershell". It will list all possible way of running Windows PowerShell. Run it as an administrator. +* In the PowerShell window, type `wsl --install` +* Restart your computer + +## Ubuntu installation + +Ubuntu (20.04) is installed automatically. + +* After the reboot a Ubuntu WSL window will open and after a short while you will be asked to create a Username and Password for the OS being installed. Choose something yourself you can remember ;) +* It is good practice to first load any updates, so type `sudo apt-get update` and press enter to check for updates, and `sudo apt-get upgrade` to install all the available updates. The `sudo` in this command tells the OS to do an update while being logged in as SuperUser (SUDO stands for SuperUser Do). It will ask for the password you used when you installed the OS. Without it you can't run these sorts of commands, so don't forget it! + +## Settings up the build system + +Now that you have an up to date Ubuntu 20.04 Linux WSL2 ready, it's time to configure it for EdgeTX. Most of the hard work will be done for you via a per-prepared script. But before you run that, you have to enable support for the i386 libraries in order to be able to compile, and then you can download and run the installation helper script. + +* To enable the needed i386 support, run +``` +sudo dpkg --add-architecture i386 +``` +* To download the installer script, run +``` +wget https://raw.githubusercontent.com/EdgeTX/edgetx/main/tools/setup_buildenv_ubuntu20.04.sh +``` +* in order to make the script executable (so you can run it), run +``` +chmod a+x setup_buildenv_ubuntu20.04.sh +``` +* To finally execute/run the installer script, run +``` +./setup_buildenv_ubuntu20.04.sh +``` + +If all went smoothly, you should not have seen any errors. + +Although the script suggests you need to reboot the computer, this is not generally the case, and is partly defeats the purpose of WSL2. All that is needed is for you to run +``` +source ~/.bashrc +``` +in order for some settings to the path to be applied. + +## For Windows 11 you're now done and you can switch to the Ubuntu Guide + +- [Ubuntu 20.04 Build Instructions](linux-ubuntu-22.04.md) + +## Preparing for graphical applications + +* Now we will immediately install the terminator we need to connect to the X-window later: `sudo apt-get install terminator` and press enter. +Accept all confirmation requests and enter your password when needed. +* As preparation for later we will install a graphical editor you may like: `sudo apt install gedit` and press enter. +You can try to run it, but since we have no graphical output yet, that wont work. We will use it later. + +If you are not familiar with Ubuntu or other Linux systems, things might be scary. Don't worry, we are not going to do much with it. just type "exit" and press enter to close down Ubuntu properly and close the terminal window. Use the shortcut if windows created it to start it again, or search for "Ubuntu" using the loupe again. + +### VcXserver installation + +This will enable us to run an application with a graphical output, such as the simulator, or companion, on our fresh Ubuntu install. + +* First you need to download it [from here](https://sourceforge.net/projects/vcxsrv/) and install it as administrator. +* Then we will create a shortcut on the desktop so we can start it like we want it. Rightclick anywhere on the screen, select new, shortcut and add the following text as destination: `"C:\Program Files\VcXsrv\vcxsrv.exe" :0 -ac -terminate -lesspointer -multiwindow -clipboard -wgl -dpi auto` +* Finally, we need a VBS script that we can start from a second shortcut to launch Ubuntu in the X-window. +* Go to the public documents folder `C:\Users\Public\Documents` or any other place you can remember. +Create a new text document (rightclick anywhere on the desktop, select new, textfile) and name it "startTerminator.txt". Open it and enter the following text: `args = "-c" & " -l " & """DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0 terminator""" +WScript.CreateObject("Shell.Application").ShellExecute "bash", args, "", "open", 0` +* Rename it to "startTerminator.vbs". +* Go to the desktop and create a shortcut (rightclick on the screen, select new, shortcut) and enter the following text: `C:\Windows\System32\wscript.exe C:\Users\Public\Documents\startTerminator.vbs` +This finishes the install. + +### How to start using it + +* Now to test all this, I suggest to disable the firewall for a moment. Use the windows search loupe or press Window(KEY)+R and type 'firewall', open it, and disable it for all three levels. If you want, you can shut down your wifi first for security reasons. +* now, first open the Xserver by clicking on the shortcut we made for it +* then open the Ubuntu session and link it to the Xserver by clicking on the second shortcut. +* Make sure you start both as ADMINISTRATOR +* You should now, after a short delay, get an Ubuntu terminal window, but now running within the Xserver window. +* we can now start using our graphical text editor we installed earlier. type `gedit` and enter. +* after all this is working, you can start the firewall again, and start tweaking it to allow the WSL to communicate properly with the firewall active. +* At least you should allow VcXserver windows Xserver as app to have acces to both private and public networks. + +## Running the SIMU + +We have created a SIMU application for the Taranis X9D+ by compiling it for you. If you want to test it, just type the following command to fetch it `wget -q https://raw.githubusercontent.com/wiki/EdgeTX/edgetx/files/simu/simu_x9dplus_ubuntu`. +then `chmod a+x simu_x9dplus_ubuntu` and run it with `./simu_x9dplus_ubuntu`. +And your X9D+ simple simulator is running in an Ubuntu window on your windows computer. (the key shortcuts can be found in the windows companion help screen: PG-UP->MENU; PG-DN->PAGE; DEL/ESC/BKSP->EXIT; +->+; -->-; ENTER->ENT). + +## Compiling + +In order to make the instructions that are on another WIKI page for setting up UBUNTU to compile, there is only one thing you need to do first. + +* You have to enable the support for the i386 libraries by executing the following commands in UBUNTU: +* `sudo dpkg --add-architecture i386` +* `sudo apt-get update` + +Now you can just follow the standard UBUNTU guide, and off you go! + +- [Ubuntu 20.04 Build Instructions](linux-ubuntu-22.04.md) + +## Some tips for Windows adepts + +* You can start an explorer from ubuntu, that will allow you to access the UBUNTU files SAFELY from windows. Simple type `explorer.exe` in UBUNTU +In the explorer you open from UBUNTU in windows: +* The UBUNTU files are under `\\wsl$\Ubuntu-20.04\` + +Make sure you know where you are in UBUNTU: + +* the UBUNTU terminal starts in your personal directory in UBUNTU, just one level below `/HOME`. So type `cd/HOME`, and then `dir`, and you can see where your personal files are for your UBUNTU user. +* The X-windows terminal starts in `/mnt/c/Windows/System32`. To switch quickly to your home directory type `cd /HOME` + +## Conclusion + +You can thus set up companion on UBUNTU to use your windows directories for the SDcard and the ETX files, working seamless together with windows from an UBUNTU X-window. The same goes for the simulator. + +In essence, from a functional perspective, Companion24 and the full Simulator24 will be exact the same as if they where compiled and run under windows directly. diff --git a/docs/building/macos-catalina.md b/docs/building/macos-catalina.md new file mode 100644 index 000000000..79779930b --- /dev/null +++ b/docs/building/macos-catalina.md @@ -0,0 +1,134 @@ +# Build Instructions using macOS 10.15 (Catalina) + +### Install Xcode command line tools: + +- Open `Terminal` +- Run this command: +``` +xcode-select —install +``` + +### Install "brew" (https://brew.sh): + +- Run command in `Terminal`: +``` +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +``` + +### Install newer Python version: + +- Run command in `Terminal`: +``` +brew install python +``` + +### Install Qt 5.12.9: + +- Install `aqtinstall` Python package: + +``` +pip3 install aqtinstall +``` + +- Install Qt 5.12.9 +``` +aqt install 5.12.9 mac desktop clang_64 +``` + +Once Qt has been installed properly, you should set a couple environment variables (please modify according to the real installation paths): +``` +export QTDIR=/Users/etx/Src/Qt/5.12.9/clang_64 +export QT_PLUGIN_PATH=$QTDIR/plugins +``` + +Please note that `QT_PLUGIN_PATH` is required to be able to run Companion from your build directory without having to build a `DMG` package first. + +### Install ARM toolchain + +Download and install ARM GCC from here (installs in `/Applications/ARM/`): +- https://developer.arm.com/-/media/Files/downloads/gnu-rm/10-2020q4/gcc-arm-none-eabi-10-2020-q4-major-mac.pkg + +Please note that this installation takes care of allowing the binaries to be run and "un-quarantines" them. If you choose to install the `bz2` archive to another location, you will have to take care of that yourself (see https://disable-gatekeeper.github.io/ for more details). + +### Install various dependencies + +- With `brew` in a `Terminal`: +``` +brew install sdl fox cmake +``` + +- Install Python dependencies: +``` +pip3 install Pillow clang lz4 jinja2 +``` + +- If you face issues from pip3 command, try to fix your CommandLineTools installation +From the terminal run: +``` +softwareupdate --list +``` +which produces a list of available updates. Wait a bit for a list to display (won't take very long). And look for the "* Label:" under Software Update found the following new or updated software: + +It should say something like: * Label: `Command Line Tools for Xcode-13.2` + +Then simply run: +``` +softwareupdate -i "Command Line Tools for Xcode-13.2" +``` +and replace the text in the brackets with the Label from the previous output. This will then install the updates and the fix for python3. + +### Compile EdgeTX + +- Checkout code +``` +git clone --recursive https://github.com/EdgeTX/edgetx.git +``` + +- Switch into the source directory: +``` +cd edgetx +``` + +- Create build directory and configure build using `cmake`: +``` +mkdir -p build + +cd build + +cmake -DPCB=X10 -DPCBREV=TX16S \ + -DCMAKE_PREFIX_PATH=$QTDIR \ + -DARM_TOOLCHAIN_DIR=/Applications/ARM/bin/ \ + -DPYTHON_EXECUTABLE=$(brew --prefix)/bin/python3 .. +``` + +Please note that the variables `CMAKE_PREFIX_PATH`, `ARM_TOOLCHAIN_DIR` and `PYTHON_EXECUTABLE` must be specified additionally to what is described in the other compilation HowTos: +- `CMAKE_PREFIX_PATH`: this must point to your Qt installation path. +- `ARM_TOOLCHAIN_DIR`: this must point to where ARM GCC has been installed (and MUST contain `/` at the end). +- `PYTHON_EXECUTABLE`: this allows overriding Python installed as part of MacOS. + +- Then build as usual (`-j4` to use 4 CPU cores): +``` +make -j4 firmware +``` + +## Notes on compiling simulator plug-ins + +When compiling simulator plug-ins (using `make libsimulator` with the target properly configured), the product of this compilation will be a `.dylib` stored in your build directory. If you want the Companion or Simulator Apps to be able to use it, you will need to copy it manually into the respective directories. Here is how it show look like with a couple plug-ins copied: + +``` +% ls -l companion.app/Contents/MacOS/ +total 411976 +-rwxr-xr-x 1 etx staff 27908864 Jan 7 11:48 companion +-rwxr-xr-x 1 etx staff 57089384 Jan 7 11:22 libedgetx-nv14-simulator.dylib +-rwxr-xr-x 1 etx staff 61167768 Jan 7 08:44 libedgetx-tx16s-simulator.dylib +-rwxr-xr-x 1 etx staff 60327272 Jan 5 12:48 libedgetx-x10express-simulator.dylib +-rwxr-xr-x 1 etx staff 1849768 Dec 26 08:56 libedgetx-x9d+-simulator.dylib +-rwxr-xr-x 1 etx staff 1881224 Dec 31 16:44 libedgetx-zorro-simulator.dylib + +% ls -l simulator.app/Contents/MacOS/ +total 392616 +-rwxr-xr-x 1 etx staff 57089384 Jan 7 11:22 libedgetx-nv14-simulator.dylib +-rwxr-xr-x 1 etx staff 61168056 Jan 5 11:52 libedgetx-tx16s-simulator.dylib +-rwxr-xr-x 1 etx staff 60327272 Jan 5 12:34 libedgetx-x10express-simulator.dylib +-rwxr-xr-x 1 etx staff 21732144 Jan 7 11:48 simulator +``` diff --git a/docs/building/macos-sequoia.md b/docs/building/macos-sequoia.md new file mode 100644 index 000000000..0839fb2b9 --- /dev/null +++ b/docs/building/macos-sequoia.md @@ -0,0 +1,165 @@ +# Build Instructions using macOS 15 (Sequoia) and macOS 26 (Tahoe) + +# Install [Homebrew](https://brew.sh/) + +- Run command in `Terminal`: +``` +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +``` +> [!TIP] +> Installing Brew via the command above will automatically install the [Xcode Command Line Tools](https://mac.install.guide/commandlinetools/). If for some reason you need to do this manually, run `xcode-select —install` via the Terminal app. + +# Install Qt 6 +> [!NOTE] +> If you only intend on building the firmware, and not `simu`, `companion` or `simulator`, this is not necessary, and you can skip to the next step. + +``` +brew install qt@6 +``` + +Once Qt has been installed, you should set a couple environment variables (please modify according to the real installation paths): +``` +export QTDIR=$(brew --prefix)/opt/qt@6 +export QT_PLUGIN_PATH=$QTDIR/plugins +``` + +Please note that `QT_PLUGIN_PATH` is required to be able to run Companion from your build directory without having to build a `DMG` package first. + +# Install ARM toolchain + +Download and install the ARM GCC toolchain [from here](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads) (installs in `/Applications/ArmGNUToolchain/`): + +- For Intel Mac: https://developer.arm.com/-/media/Files/downloads/gnu/14.2.rel1/binrel/arm-gnu-toolchain-14.2.rel1-darwin-x86_64-arm-none-eabi.pkg +- If Mac Silicon (i.e. M1-M5): https://developer.arm.com/-/media/Files/downloads/gnu/14.2.rel1/binrel/arm-gnu-toolchain-14.2.rel1-darwin-arm64-arm-none-eabi.pkg + +Please note that this installation takes care of allowing the downloaded binaries to be run and prevents them being quarantined. If you choose to install the `tar.xz` archive to another location, you will have to take care of that yourself (see https://disable-gatekeeper.github.io/ for more details). + +# Install various dependencies + +- With `brew` in a `Terminal`: +``` +brew install sdl cmake +``` + +If you plan to run the standalone simulator for debugging: +``` +brew install --cask quartz +``` + + +# Download EdgeTX code + +- Checkout code +``` +git clone --recursive https://github.com/EdgeTX/edgetx.git +``` + +- Switch into the source directory: +``` +cd edgetx +``` + +# Install Python dependencies + +Since Python 3.11 enabled the "externally managed" flag, it is recommended that you use a virtual environment. [uv](https://docs.astral.sh/uv/getting-started/installation/) is one of the easiest tools to do and manage this, and can be installed with brew. It is recommended you create the virtual environment now rather than earlier in the process, as doing it now will create it in the edgetx directory. + +- Install UV: +``` +brew install uv +``` + +- Create the virtual environment (and use specific version of python for this environment): +``` +uv venv --python 3.14 +``` + +- Activate the virtual environment (you will need to run this whenever you want to compile in the future from a new terminal session): +``` +source .venv/bin/activate +``` + +- Install the packages: +``` +uv pip install Pillow clang lz4 jinja2 +``` + +# Compile EdgeTX + +- Create and enter build directory: +``` +mkdir -p build && cd build +``` + +Configure build flags using `cmake` (in this case, for RadioMaster TX16S, [see here](https://github.com/EdgeTX/edgetx/blob/main/tools/build-common.sh) for other possible handset specific flags). +``` +cmake -DPCB=X10 -DPCBREV=TX16S \ + -DCMAKE_PREFIX_PATH=$QTDIR \ + -DARM_TOOLCHAIN_DIR=/Applications/ArmGNUToolchain/14.2.Rel1/arm-none-eabi/bin/ .. +``` + +> [!NOTE] +> Please note that the variables `CMAKE_PREFIX_PATH`, `ARM_TOOLCHAIN_DIR` must be specified additionally to what is described in the other compilation HowTos: +> - `CMAKE_PREFIX_PATH`: this must point to your Qt installation path. +> - `ARM_TOOLCHAIN_DIR`: this must point to where ARM GCC has been installed (and MUST contain `/` at the end). + +Configure the compiler for firmware building (parallel limits the number of CPU cores used - you can increase this if your machine can handle more): +``` +cmake --build . --target arm-none-eabi-configure --parallel 4 +``` + +Build the firmware! +``` +cmake --build . --target firmware +``` + +# Troubleshooting + +## Notes on compiling simulator plug-ins + +When compiling simulator plug-ins (using `cmake --build . --target libsimulator` with the target properly configured), the product of this compilation will be a `.dylib` stored in your build directory. If you want the Companion or Simulator apps to be able to use it, you will need to copy it manually into the respective directories. Here is how it should look with a couple of plug-ins copied: + +``` +% ls -l companion.app/Contents/MacOS/ +total 411976 +-rwxr-xr-x 1 etx staff 27908864 Jan 7 11:48 companion +-rwxr-xr-x 1 etx staff 57089384 Jan 7 11:22 libedgetx-nv14-simulator.dylib +-rwxr-xr-x 1 etx staff 61167768 Jan 7 08:44 libedgetx-tx16s-simulator.dylib +-rwxr-xr-x 1 etx staff 60327272 Jan 5 12:48 libedgetx-x10express-simulator.dylib +-rwxr-xr-x 1 etx staff 1849768 Dec 26 08:56 libedgetx-x9d+-simulator.dylib +-rwxr-xr-x 1 etx staff 1881224 Dec 31 16:44 libedgetx-zorro-simulator.dylib + +% ls -l simulator.app/Contents/MacOS/ +total 392616 +-rwxr-xr-x 1 etx staff 57089384 Jan 7 11:22 libedgetx-nv14-simulator.dylib +-rwxr-xr-x 1 etx staff 61168056 Jan 5 11:52 libedgetx-tx16s-simulator.dylib +-rwxr-xr-x 1 etx staff 60327272 Jan 5 12:34 libedgetx-x10express-simulator.dylib +-rwxr-xr-x 1 etx staff 21732144 Jan 7 11:48 simulator +``` + +## Notes on possible error while trying to run build-companion.sh + +If you encounter this error: +``` +CPack: - Install project: EdgeTX [] +CMake Error at /opt/homebrew/Cellar/cmake/3.27.7/share/cmake/Modules/BundleUtilities.cmake:458 (message): + otool -l failed: 1 + + error: + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/otool-classic: + can't open file: @rpath/libsharpyuv.0.dylib (No such file or directory) + +Call Stack (most recent call first): + /opt/homebrew/Cellar/cmake/3.27.7/share/cmake/Modules/BundleUtilities.cmake:527 (get_item_rpaths) + /opt/homebrew/Cellar/cmake/3.27.7/share/cmake/Modules/BundleUtilities.cmake:614 (set_bundle_key_values) + /opt/homebrew/Cellar/cmake/3.27.7/share/cmake/Modules/BundleUtilities.cmake:933 (get_bundle_keys) + /Users/jean-christophedreyfus/Documents/edgetx/build/native/companion/src/cmake_install.cmake:180 (fixup_bundle) + /Users/jean-christophedreyfus/Documents/edgetx/build/native/cmake_install.cmake:43 (include) + + +CPack Error: Error when generating package: companion +make: *** [package] Error 1 +``` + +It can be fixed by entering the following command at terminal: + +`install_name_tool -change "@rpath/libsharpyuv.0.dylib" "$(brew --prefix)/lib/libsharpyuv.0.dylib" "$(brew --prefix)/lib/libwebp.7.dylib" && codesign --force -s - "$(brew --prefix)/lib/libwebp.7.dylib"` diff --git a/docs/building/macos-sonoma.md b/docs/building/macos-sonoma.md new file mode 100644 index 000000000..3993fdac4 --- /dev/null +++ b/docs/building/macos-sonoma.md @@ -0,0 +1,144 @@ +# Build Instructions using macOS 14.1 (Sonoma) + +### Install Xcode command line tools: + +- Open `Terminal` +- Run this command: +``` +xcode-select —install +``` + +### Install "brew" (https://brew.sh): + +- Run command in `Terminal`: +``` +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +``` + +### Install newer Python version: + +- Run command in `Terminal`: +``` +brew install python +``` + +### Install Qt 5: +``` +brew install qt@5 +``` + +Once Qt has been installed properly, you should set a couple environment variables (please modify according to the real installation paths): +``` +export QTDIR=$(brew --prefix)/opt/qt@5 +export QT_PLUGIN_PATH=$QTDIR/plugins +``` + +Please note that `QT_PLUGIN_PATH` is required to be able to run Companion from your build directory without having to build a `DMG` package first. + +### Install ARM toolchain + +Download and install ARM GCC from here (installs in `/Applications/ARM/`): +- https://developer.arm.com/-/media/Files/downloads/gnu/13.2.rel1/binrel/arm-gnu-toolchain-13.2.rel1-darwin-x86_64-arm-none-eabi.pkg + +Please note that this installation takes care of allowing the binaries to be run and "un-quarantines" them. If you choose to install the `bz2` archive to another location, you will have to take care of that yourself (see https://disable-gatekeeper.github.io/ for more details). + +### Install various dependencies + +- With `brew` in a `Terminal`: +``` +brew install sdl fox cmake +``` + +If you plan to run the standalone simulator for debuging +``` +brew install --cask quartz +``` + +- Install Python dependencies: +``` +pip3 install Pillow clang lz4 jinja2 +``` + +### Compile EdgeTX + +- Checkout code +``` +git clone --recursive https://github.com/EdgeTX/edgetx.git +``` + +- Switch into the source directory: +``` +cd edgetx +``` + +- Create build directory and configure build using `cmake`: +``` +mkdir -p build + +cd build + +cmake -DPCB=X10 -DPCBREV=TX16S \ + -DCMAKE_PREFIX_PATH=$QTDIR \ + -DARM_TOOLCHAIN_DIR=/Applications/ArmGNUToolchain/13.2.Rel1/arm-none-eabi/bin/ \ + -DPYTHON_EXECUTABLE=$(brew --prefix)/bin/python3 .. +``` + +Please note that the variables `CMAKE_PREFIX_PATH`, `ARM_TOOLCHAIN_DIR` and `PYTHON_EXECUTABLE` must be specified additionally to what is described in the other compilation HowTos: +- `CMAKE_PREFIX_PATH`: this must point to your Qt installation path. +- `ARM_TOOLCHAIN_DIR`: this must point to where ARM GCC has been installed (and MUST contain `/` at the end). +- `PYTHON_EXECUTABLE`: this allows overriding Python installed as part of MacOS. + +- Then build as usual (`-j4` to use 4 CPU cores): +``` +make -j4 firmware +``` + +## Notes on compiling simulator plug-ins + +When compiling simulator plug-ins (using `make libsimulator` with the target properly configured), the product of this compilation will be a `.dylib` stored in your build directory. If you want the Companion or Simulator Apps to be able to use it, you will need to copy it manually into the respective directories. Here is how it show look like with a couple plug-ins copied: + +``` +% ls -l companion.app/Contents/MacOS/ +total 411976 +-rwxr-xr-x 1 etx staff 27908864 Jan 7 11:48 companion +-rwxr-xr-x 1 etx staff 57089384 Jan 7 11:22 libedgetx-nv14-simulator.dylib +-rwxr-xr-x 1 etx staff 61167768 Jan 7 08:44 libedgetx-tx16s-simulator.dylib +-rwxr-xr-x 1 etx staff 60327272 Jan 5 12:48 libedgetx-x10express-simulator.dylib +-rwxr-xr-x 1 etx staff 1849768 Dec 26 08:56 libedgetx-x9d+-simulator.dylib +-rwxr-xr-x 1 etx staff 1881224 Dec 31 16:44 libedgetx-zorro-simulator.dylib + +% ls -l simulator.app/Contents/MacOS/ +total 392616 +-rwxr-xr-x 1 etx staff 57089384 Jan 7 11:22 libedgetx-nv14-simulator.dylib +-rwxr-xr-x 1 etx staff 61168056 Jan 5 11:52 libedgetx-tx16s-simulator.dylib +-rwxr-xr-x 1 etx staff 60327272 Jan 5 12:34 libedgetx-x10express-simulator.dylib +-rwxr-xr-x 1 etx staff 21732144 Jan 7 11:48 simulator +``` + +## Notes on possible error while trying to run build-companion.sh + +If you encounter this error: +``` +CPack: - Install project: EdgeTX [] +CMake Error at /opt/homebrew/Cellar/cmake/3.27.7/share/cmake/Modules/BundleUtilities.cmake:458 (message): + otool -l failed: 1 + + error: + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/otool-classic: + can't open file: @rpath/libsharpyuv.0.dylib (No such file or directory) + +Call Stack (most recent call first): + /opt/homebrew/Cellar/cmake/3.27.7/share/cmake/Modules/BundleUtilities.cmake:527 (get_item_rpaths) + /opt/homebrew/Cellar/cmake/3.27.7/share/cmake/Modules/BundleUtilities.cmake:614 (set_bundle_key_values) + /opt/homebrew/Cellar/cmake/3.27.7/share/cmake/Modules/BundleUtilities.cmake:933 (get_bundle_keys) + /Users/jean-christophedreyfus/Documents/edgetx/build/native/companion/src/cmake_install.cmake:180 (fixup_bundle) + /Users/jean-christophedreyfus/Documents/edgetx/build/native/cmake_install.cmake:43 (include) + + +CPack Error: Error when generating package: companion +make: *** [package] Error 1 +``` + +It can be fixed by entering the following command at terminal: + +`install_name_tool -change "@rpath/libsharpyuv.0.dylib" "$(brew --prefix)/lib/libsharpyuv.0.dylib" "$(brew --prefix)/lib/libwebp.7.dylib" && codesign --force -s - "$(brew --prefix)/lib/libwebp.7.dylib"` diff --git a/docs/building/qt-creator.md b/docs/building/qt-creator.md new file mode 100644 index 000000000..55df6d7fc --- /dev/null +++ b/docs/building/qt-creator.md @@ -0,0 +1,189 @@ +# Building and Debugging with Qt Creator + +!!! warning "Obsolete" + **The info in this page is obsolete and does not work anymore with present EdgeTX versions.** This guide is no longer maintained and is provided for historical reference only. The configuration steps described here were written for much older versions of EdgeTX and Qt Creator. + +This page discusses how to setup and use [Qt Creator](https://wiki.qt.io/QtCreatorWhitepaper) graphical integrated development environment (IDE) to explore and also debug EdgeTX source code. + +- [Configuring Qt Creator for EdgeTX](#configuring-qt-creator-for-edgetx) + * [Activating BareMetal plugin](#activating-baremetal-plugin) + * [Adding GNU ARM compiler and debugger support to Qt Creator](#adding-gnu-arm-compiler-and-debugger-support-to-qt-creator) + * [Creating a bare metal device and adding a debugging option to it](#creating-a-bare-metal-device-and-adding-a-debugging-option-to-it) + * [Creating a Kit for building firmware for STM32 µCs](#creating-a-kit-for-building-firmware-for-stm32-cs) +- [Loading EdgeTX source tree into Qt Creator](#loading-edgetx-source-tree-into-qt-creator) +- [Building EdgeTX firmware with Qt Creator](#building-edgetx-firmware-with-qt-creator) +- [Editing source code with Qt Creator](#editing-source-code-with-qt-creator) + +[![Qt Creator code completion](../assets/images/build/qtcreator/QtCodeCompletion.png)](../assets/images/build/qtcreator/QtCodeCompletion.png) + +With [Qt Creator](https://wiki.qt.io/QtCreatorWhitepaper), you not only have a graphical option to build EdgeTX radio firmware, Companion and Simulator software, but also very comfortable way to edit the code and even more importantly to debug it. If you hook up to your radio's [Serial-Wire-Debug (SWD)](https://stm32-base.org/guides/connecting-your-debugger.html) header of the mainboard a hardware debugger, it is possible to perform in-circuit-debugging of code running on the radios STM32 microcontroller. Some examples of hardware debuggers that can be used are, e.g. [Segger J-Link](https://www.segger.com/products/debug-probes/j-link/) (incl. the [Mini EDU](https://www.segger.com/products/debug-probes/j-link/models/j-link-edu-mini/)) and [ST-Link/V2](https://www.st.com/en/development-tools/st-link-v2.html). With in-circuit-debugging, you are able to step through the code and do live variable inspection, which makes validating low level code much easier. For debugging high-level code, it is easier to use the radio firmware simulation library, running on your PC, not requiring a physical radio hardware hookup. Even if you might not be driven by the desire to change the existing EdgeTX codebase, running code in a debug session will provide you an in-depth insight into variables passed between the functions and can in general give a clearer view of how the EdgeTX runs under the hood. + +If you followed the previous build instruction guides (irrespective if for Windows 10 or Ubuntu Linux 20.04), Qt Creator IDE is already installed on your system. +The guide below uses screenshots from Windows, but provides info for correct paths in text for Ubuntu Linux as well. + +## Configuring Qt Creator for EdgeTX + +We need to first configure Qt Creator to support building for ARM architecture and external debugging (so called _bare-metal_ in Qt Creator lingo). + +### Activating BareMetal plugin + +Launch Qt Creator by clicking on _Start_ -> _Qt_ -> _Qt Creator_. Navigate to menu _Help_ and click _About Plugins..._. Under _Device Support_ enable the _BareMetal (experimental)_ plugin. Click _Close_ + +[![Qt Creator BareMetal plugin](../assets/images/build/qtcreator/QtCreatorBareMetal.png)](../assets/images/build/qtcreator/QtCreatorBareMetal.png) + +After this step, it is mandatory to restart Qt Creator, select _Restart Now_ from the pop-up to restart Qt Creator. + +### Adding GNU ARM compiler and debugger support to Qt Creator + +Open from menu _Tools_ -> _Options..._. In the left pane _Kits_ should already be selected, if not, select it. Open tab _Compilers_. Click _Add_ -> _GCC_ -> _C_. As name, enter for example `GCC C ARM`. Click _Browse..._ behind field _Compiler path_ and navigate and open + + * Windows: `C:\Program Files (x86)\GNU Arm Embedded Toolchain\10 2020-q4-major\bin\arm-none-eabi-gcc.exe` + * Linux: `/opt/gcc-arm-none-eabi/bin/arm-none-eabi-gcc` + +Field _ABI:_ should have automatically detected _arm-baremetal-generic-elf-32bit_. Click _Apply_. + +Next, we add similarly C++ compiler. Click _Add_ -> _GCC_ -> _C++_. As name, enter for example `GCC ARM` and into field _Compiler path_ enter the same _arm-none-eabi-gcc_ binary as in the last step for plain C. Also here, field _ABI:_ should have detected _arm-baremetal-generic-elf-32bit_. Click once more _Apply_. If everything went smoothly, the red exclamation marks should be gone. + +[![Qt Creator Compilers](../assets/images/build/qtcreator/QtCreatorCompilers.png)](../assets/images/build/qtcreator/QtCreatorCompilers.png) + +Navigate to _Debuggers_ tab. Click _Add_, provide as name for example _GDB ARM_ and click _Browse..._ behind field _Path:_ + +Navigate to: + + * Windows: `C:\Program Files (x86)\GNU Arm Embedded Toolchain\10 2020-q4-major\bin\arm-none-eabi-gdb-py.exe` + * Linux: `/opt/gcc-arm-none-eabi/bin/arm-none-eabi-gdb-py` + +and click _Open_. If Qt Creator is happy, then it should list in _Type_ and _ABIs_ fields that it found _GDB_ for _arm-baremetal-generic-elf-32bit_. Click _Apply_. + +[![Qt Creator Debuggers](../assets/images/build/qtcreator/QtCreatorDebuggers.png)](../assets/images/build/qtcreator/QtCreatorDebuggers.png) + +### Creating a bare metal device and adding a debugging option to it + +If you plan to carry out in-circuit debugging, them install the drivers and software for your debugging hardware before continuing. For Segger J-Link/J-Trace, get the latest [Segger J-Link software and documentation pack](https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack) and install it. If your debugger stems from another manufacturer, you might want to consider the Open On-Chip Debugger or short [OpenOCD](http://openocd.org/). It supports huge variety of debugger hardware, but is less trivial to setup. + +To add in-circuit-debugging to Qt Creator, start by navigating in the left pane of the Options dialog to _Devices_. Open tab _Bare Metal_, click _Add_ and according to your debugger hardware choose either _JLink_ or _OpenOCD_. The example below shows how to setup in-circuit-debugging with Segger J-Link/J-Trace. + +click _Browse..._ behind _Executable file_ and open the command line version of J-Link GDB Server binary at: + + * Windows: `C:\Program Files (x86)\SEGGER\JLink\JLinkGDBServerCL.exe` + * Linux: `/opt/SEGGER/JLink/JLinkGDBServer` + +Make sure the _Target interface_ is set to _SWD_ and adjust the speed according to your J-Link hardware (the [following page](https://www.segger.com/products/debug-probes/j-link/models/model-overview/) lists the maximum target interface speed of Segger products). Under _Device:_ use the STM32 chip according to your hardware. For Jumper T16 and RadioMaster TX16S, this is for example _STM32F429BI_. +The remaining settings can be left at default, click _Apply_ + +[![Qt Creator JLink setup](../assets/images/build/qtcreator/QtCreatorJLink.png)](../assets/images/build/qtcreator/QtCreatorJLink.png) + +Navigate to tab _Devices_. Click _Add.._, pick _Bare Metal Device_ and click _Start Wizard_. Give it a name, such as `STM32`. Pick a _GDB server provider:_ according to your debugger hardware either _JLink_ or _OpenOCD_. If you do not possess a debugger hardware, you can choose _None_ here. Click _Finish_, click _Apply_. + +[![Qt Creator Devices](../assets/images/build/qtcreator/QtCreatorDevices.png)](../assets/images/build/qtcreator/QtCreatorDevices.png) + +### Creating a Kit for building firmware for STM32 µCs + +This step gathers the options for building for STM32 microcontrollers that we have prepared in the last steps. + +In the left pane of Qt Creator Options dialog, choose _Kits_ and navigate to similarly named tab _Kits_. Add a new kit by clicking _Add_. Give it a name, like `STM32`. Under _Device type:_ pick _Bare Metal Device_. + +If under _Device:_ _STM32 (default for Bare Metal)_ is not already automagically selected, pick it from the drop-down box. In fields _Compiler:_ choose our previously prepared _GCC C ARM_ and _GCC ARM_ options. For field _Debugger:_, choose our prepared _GDB ARM_. As there is no Qt code in our firmware for radio µC, select `None` for the _Qt version_. Click _Apply_. + +Next, we need to result to a trick to disable CMake to run a so called _simple test_, when loading a project. This is required to avoid a warning in present cross-compilation situation (cross-compilation here means that we compile for ARM architecture in STM32 microcontrollers under x86/x64 architecture). Click _Change..._ behind _CMake Configuration_ and append the following two lines in _Edit CMake Configuration_ dialog: +``` +CMAKE_CXX_COMPILER_WORKS:STRING=1 +CMAKE_C_COMPILER_WORKS:STRING=1 +``` +and click _OK_ for the _Edit CMake Configuration_ dialog. Click _Apply_ in the Qt Creator Options dialog. + +[![Qt Creator CMake Configuration](../assets/images/build/qtcreator/QtCreatorCMakeConfiguration.png)](../assets/images/build/qtcreator/QtCreatorCMakeConfiguration.png) + +Verify that in the Kits list, our newly created _STM32_ kit is selected, then click _Make Default_ + +[![Qt Creator Kits](../assets/images/build/qtcreator/QtCreatorKits.png)](../assets/images/build/qtcreator/QtCreatorKits.png) + +Depending on your hardware debugger maximum target speed, flashing STM32 µC in the radio can take some moments. The default wait time in Qt Creator for GNU debugger (GDB) is 20 seconds, which is typically a bit short for STM32 chips with larger memories and results in an unnecessary pop-up. Next, we will prolong the default waiting time. In the left pane of Qt Creator Options dialog click _Debugger_ and navigate to _GDB_ tab. Set _GDB timeout_, e.g. to 60 seconds: + +[![Qt Creator GDB timeout](../assets/images/build/qtcreator/QtGDBtimeout.png)](../assets/images/build/qtcreator/QtGDBtimeout.png) + +Click _OK_ to close the options dialog. + +This concludes setting up Qt Creator for EdgeTX. + +## Loading EdgeTX source tree into Qt Creator + +In the following, we assume that you followed the instructions setting up the build environment and building EdgeTX firmware (for Windows 10 or for Ubuntu 20.04) and have created a dedicated EdgeTX folder (`C:\edgetx` for Windows or `~/edgetx` for Linux) and downloaded or git cloned EdgeTX source under this dedicated folder. + +For the sake of clarity, we will create two new folders to put the output of our Qt build. Create two new empty folders: + + * Windows: `C:\edgetx\build-edgetx-qt-fw` and `C:\edgetx\build-edgetx-qt-comp_sim_libsim` + * Linux: `~/edgetx/edgetx-v2.4/build-qt-fw` and `~/edgetx/edgetx-v2.4/build-qt-comp_sim_libsim` + +Back in Qt Creator, let's import next the EdgeTX source files into a project. From Qt Creator menu, choose _File_ -> _Open File or Project..._. Open: + + * Windows: `C:\edgetx\edgetx24\CMakeLists.txt` + * Linux: `~/edgetx/edgetx-v2.4/CMakeLists.txt` + +Next we need to pick the kits for building. If not already automatically selected, pick _STM32_ that is required for building firmware for ARM architecture. Presently, only under Ubuntu, you can also select _Desktop_ to build Companion, Simulator and radio firmware simulator libraries. If there show up any _Imported Kits_, deselect them (typically only happens if you do not open the project for the first time). + +Click _Details_ behind _STM32_ to unfold a build type selection dialog. As we are presently only interested in debugging, leave it selected, but you can deselect all other three options (_Release_, _Release with Debug Information_ and _Minimum Size Release_). Click _Browse..._ behind _Debug_ and open the following folder as build output location: + + * Windows: `C:\edgetx\build-edgetx-qt-fw` + * Linux: `~/edgetx/edgetx-v2.4/build-qt-fw` + +If you opted for building also Companion, Simulator and radio firmware simulator libraries under Ubuntu, click _Details_ behind _Desktop_ and also here, leave only _Debug_ selected. Click _Browse..._ and provide `~/edgetx/edgetx-v2.4/build-qt-comp_sim_libsim` as build target location. + +[![Qt Creator Project Kit Selection](../assets/images/build/qtcreator/QtCreatorProjectKitSelection.png)](../assets/images/build/qtcreator/QtCreatorProjectKitSelection.png) + +Click _Configure Project_. + +Click on _Projects_ on the left vertical button bar (so called Mode Selector) and verify that _STM32_ -> _Build_ is currently selected. + +Qt Creator presents us the build configuration options as a selection list. These match the previous CMake command line options. As an example, we will select to build for RadioMaster TX16S using matching options we listed in the command line build example for Windows 10 and Ubuntu Linux 20.04 pages. + + * Look for DEFAULT -> DEFAULT_MODE and enter 2 into the value field on the right + * GVARS should be already selected + * Disable HELI (if you like) + * LUA -> LUA should already be selected + * PCB list is presented as a drop-down options list, choose here `X10` for TX16S + * type in PCBREV field `TX16S` (instead of default 2014) + * under PPM -> PPM_UNIT, select US from the dropdown list + +Please note that _INTERNAL_GPS_ is not listed, so we need to add it manually. Click _Add_, select as type _Boolean_ and type `INTERNAL_GPS` and select it (make the state to ON). + +[![Qt Creator CMake Options](../assets/images/build/qtcreator/QtCreatorCMakeOptions.png)](../assets/images/build/qtcreator/QtCreatorCMakeOptions.png) + +In case you plan performing in-circuit-debugging, you might want to turn off _UNEXPECTED_SHUTDOWN_, in order not to enter EdgeTX _Emergency Mode_ screen on every boot that was not previously nicely shut-down. Be aware though that this has the potential to corrupt the file system on microSD card, thus ideally use a separate card for debugging, or at least make sure the file system is OK, before you go and fly with it. + +Click _Apply Configuration Settings_. Please wait for the process to end, it can take some moments. + +Under _Build Steps_, click _Details_ to open a selection menu of what to build. Here, we only want to build and debug _firmware_, thus select _firmware_ and then deselect _all_. + +[![Qt Creator Build Steps](../assets/images/build/qtcreator/QtCreatorBuildSteps.png)](../assets/images/build/qtcreator/QtCreatorBuildSteps.png) + +We need to add two environment variables. Under _Build Environment_ click _Details_ to the right of _Use System Environment_ to unfold the variable list. +Click _Add_ and give the variable a name `C_INCLUDE_PATH` with value `C:\Program Files (x86)\GNU Arm Embedded Toolchain\10 2020-q4-major\arm-none-eabi\include` + +Click once more _Add_ to add a second environment variable with a name `CPLUS_INCLUDE_PATH` and a bit longer value `C:\Program Files (x86)\GNU Arm Embedded Toolchain\10 2020-q4-major\arm-none-eabi\include\c++\10.2.1;C:\Program Files (x86)\GNU Arm Embedded Toolchain\10 2020-q4-major\arm-none-eabi\include\c++\10.2.1\arm-none-eabi` + +[![Qt Creator Build Environment](../assets/images/build/qtcreator/QtCreatorBuildEnvironment.png)](../assets/images/build/qtcreator/QtCreatorBuildEnvironment.png) + +Now, we should have everything set up. Let's set our deploy target by clicking in the bottom left of Qt Creator window the chip symbol with OpenTX and Debug labels. Choose _STM32_ as Kit and _firmware (on STM32)_ as Run target: + +[![Qt Creator Deploy Target](../assets/images/build/qtcreator/QtCreatorDeployTarget.png)](../assets/images/build/qtcreator/QtCreatorDeployTarget.png) + +## Building EdgeTX firmware with Qt Creator + +To test if building works, click the hammer icon (Build button) on lower left corner to build firmware. On the bottom of Qt Creator window, you can navigate to _4 Compile Output_ and click it to see compiler progress. After some minutes you should have _firmware.bin_ and _firmware.elf_ files built and saved in `C:\edgetx\build-edgetx-qt-fw` + +[![Qt Creator Build Completed](../assets/images/build/qtcreator/QtCreatorBuildCompleted.png)](../assets/images/build/qtcreator/QtCreatorBuildCompleted.png) + +## Editing source code with Qt Creator + +To edit the source of EdgeTX, click in Mode Selector _Edit_. Unfold _OpenTX [2.4]_ and open a source file you would like to edit under `radio -> src -> firmware -> Source Files`. Qt Creator offers many wide established features like syntax highlighting, code completion, refactoring, integrated version control and many more. + +[![Qt Creator Code Completion](../assets/images/build/qtcreator/QtCodeCompletion.png)](../assets/images/build/qtcreator/QtCodeCompletion.png) + +For deeper instructions into Qt Creator, please see [Qt Creator Manual](https://doc.qt.io/qtcreator/). + + * You can find the code for radio firmware and libsimulator under `radio/src/firmware/Source Files` (main entry point is in `opentx.cpp`). + * Companion software is under `companion/src/companion/Source Files` (main entry point is in `companion.cpp`) + * Simulator source code you find under `companion/src/simulator/Source Files` (main entry point is in `simulator.cpp`) + +Please note that Companion, Simulator and libsimulator should be built using the _Desktop kit_ and not _STM32 kit_, as these will run on x86/x64 and not on ARM! Currently building radio simulator library does not yet work under Windows! diff --git a/docs/building/windows-docker.md b/docs/building/windows-docker.md new file mode 100644 index 000000000..0fc3ad842 --- /dev/null +++ b/docs/building/windows-docker.md @@ -0,0 +1,103 @@ +# Build Instructions using Docker and Windows 10 + +Work-in-progress page + +# Building EdgeTX on Windows 10 using Docker images + +## Download and install [Docker Desktop for Windows](https://www.docker.com/products/docker-desktop/) + +## Download and install [GWSL](https://github.com/Opticos/GWSL-Source/releases/) to run Linux Companion and Simulator + +- Run GWSL to configure it. Accept page 1 and 2 defaults and add disable access control on page 3 + + +## Fetch a local copy of the EdgeTX repository or update your existing local EdgeTX repository +``` +git clone --recursive -b main https://github.com/EdgeTX/edgetx.git EdgeTX +``` +- If you already have a local EdgeTX repository don't forget to update the submodules too, e.g.: +``` +git fetch origin +git checkout main +git submodule update --init --recursive +``` + +## Run build (example TX16s) + +- open a PowerShell +- cd to your local repository +``` +docker run --name="ETXDocker" -it --rm --mount src="$(pwd)",target="/src",type=bind ghcr.io/edgetx/edgetx-dev bash +cd src +mkdir -p build-output +cd build-output +cmake -DPCB=X10 -DPCBREV=TX16S -DCMAKE_BUILD_TYPE=Release ../ +make configure +make -C arm-none-eabi -j$(nproc) firmware +make -C native -j$(nproc) libsimulator +make -C native -j$(nproc) companion210 +make -C native -j$(nproc) simulator210 +``` +- find the results in folder build-output of your local build repository folder + +# More Cmake build options + +X9d+: +``` +-DPCB=X9D+ -DCMAKE_BUILD_TYPE=Release +``` + +X7: +``` +-DPCB=X7 -DCMAKE_BUILD_TYPE=Release +``` +TX12: +``` +-DPCB=X7 -DPCBREV=TX12 -DCMAKE_BUILD_TYPE=Release +``` + +TX16S: +``` +-DPCB=X10 -DPCBREV=TX16S -DCMAKE_BUILD_TYPE=Release +``` + +# Running Linux Companion and Simulator + +## Running Companion + +- make sure GWSL is running +- open a PowerShell +- in case you don't know your IP address enter 'ipconfig' to find out +- cd to your build folder +- remember to replace IP_OF_YOUR_WINDOWS_MACHINE with your IP address and enter: +``` +docker run --name="ETXDocker" -it --rm --mount src="$(pwd)",target="/src",type=bind ghcr.io/edgetx/edgetx-dev bash +export DISPLAY=IP_OF_YOUR_WINDOWS_MACHINE:0.0 +cd src +./native/companion210 +``` + +## Running Simulator + +- make sure GWSL is running +- open a PowerShell +- in case you don't know your IP address enter `ipconfig` to find out +- `cd` to your build folder +- remember to replace IP_OF_YOUR_WINDOWS_MACHINE with your IP address and enter: +``` +docker run --name="ETXDocker" -it --rm --mount src="$(pwd)",target="/src",type=bind ghcr.io/edgetx/edgetx-dev bash +export DISPLAY=IP_OF_YOUR_WINDOWS_MACHINE:0.0 +cd src +./native/simulator210 +``` + +# Needful things + +- Should you get a message like ```container name "/ETXDocker" is already in use``` open a PowerShell and enter ```docker stop ETXDocker``` +- If you need to update the docker image open a PowerShell and enter: ``` docker rmi ghcr.io/edgetx/edgetx-dev```. The latest image will then be downloaded at next docker run +- before running the simulator you need to run companion and create a radio profile +- companion and simulator won't have audio. If you need audio you might find [PulseAudio on WSL2](https://www.linuxuprising.com/2021/03/how-to-get-sound-pulseaudio-to-work-on.html) useful + +# References + +see [EdgeTX Build Wiki](https://github.com/EdgeTX/build-edgetx) diff --git a/docs/building/windows.md b/docs/building/windows.md new file mode 100644 index 000000000..cffb5bd24 --- /dev/null +++ b/docs/building/windows.md @@ -0,0 +1,218 @@ +# Build Instructions under Windows + +Note: The instructions on this page apply only for building V3.0.0-dev and later versions of EdgeTX. + +## Table of Contents + +* [Toolchain setup](#toolchain-setup) + 1. [Visual Studio](#visual-studio) + 2. [ARM GNU Toolchain](#arm-gnu-toolchain) + 3. [Folders for libraries of the project](#folders-for-libraries-of-the-project) + 4. [Build script](#build-script) + 5. [NSIS Windows installer creator](#nsis-windows-installer-creator) + 6. [Python package manager uv](#python-package-manager-uv) + 7. [Python virtual environment](#python-virtual-environment) + 8. [Qt development framework](#qt-development-framework) +* [Building](#building) + 1. [Fetch the EdgeTX project](#fetch-the-edgetx-project) + 2. [Target specific build script](#target-specific-build-script) + +*** + +## Toolchain setup + +### Visual Studio + +Download and start Visual Studio 2022 Community installer: https://visualstudio.microsoft.com/downloads/ + +To start the installer in English to more easily follow the selection below, open a command prompt and add `--locale en-US` to the installer executable when starting it. Under `Individual components` tab, minimally select the following components: +``` + Under Code tools: + Git for Windows + Under Compilers, build tools and runtimes: + C++ Clang Compiler for Windows (19.1.5) + C++ CMake tools for Windows + MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest) (is typically already selected by default) + Under SDKs, libraries, and frameworks: + Windows 11 SDK (10.0.26100.4654) +``` + + + +In the a dialog asking if you want to continue without workloads, you can accept just to `Continue`. You can skip making an account and logging in, if asked by the installer. + +### ARM GNU Toolchain + +Download https://developer.arm.com/-/media/Files/downloads/gnu/14.2.rel1/binrel/arm-gnu-toolchain-14.2.rel1-mingw-w64-x86_64-arm-none-eabi.exe + +Install it to default location and select Add path to environment variable. + + + +### Folders for libraries of the project + +Create a folder to hold the development environment and the project, e.g. `C:\edgetx`. + +Create a subfolder `C:\edgetx\build-tools`. + +Download https://github.com/libsdl-org/SDL/releases/download/release-2.32.8/SDL2-devel-2.32.8-VC.zip and unpack it to `C:\edgetx\build-tools\SDL2` + +### Build script + +Create `C:\edgetx\edgetx_build.cmd` with following contents: + +``` +@echo off + +time /t + +set CC=clang.exe +set CXX=clang++.exe + +set NSIS_EXE=c:\Program Files (x86)\NSIS\makensis.exe +set SDL2=%EDGETX_BUILD_TOOLS%\SDL2\cmake +set QT_DIR=%EDGETX_BUILD_TOOLS%\Qt\6.9.0\msvc2022_64 +set PATHS="-DSDL2_DIR=%SDL2%" +set CMAKE_PREFIX_PATH="-DCMAKE_PREFIX_PATH=%QT_DIR%" +set LANGUAGE="-DTRANSLATIONS=%BUILD_LANGUAGE%" + +echo ******************************************** +echo Building radio: %BUILD_RADIO% +echo Language: %BUILD_LANGUAGE% +echo Debug build: %BUILD_DEBUG% +echo Firmware: %BUILD_FW% +echo Companion: %BUILD_CPN% +echo Installer: %BUILD_INSTALLER% +echo ******************************************** + +REM +REM prepare build +REM +cd %EDGETX_REPO% + +if %BUILD_DEBUG%=="yes" ( + set BUILD_TYPE="-DDEBUG=YES;-DCMAKE_BUILD_TYPE=Debug" +) else ( + set BUILD_TYPE="-DCMAKE_BUILD_TYPE=Release" +) + +cd %EDGETX_MAIN_DIR% +set BUILD_FOLDER="build-output-%BUILD_RADIO%" +mkdir %BUILD_FOLDER% +cd %BUILD_FOLDER% +call "c:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\VsDevCmd.bat" -startdir=none -arch=x64 -host_arch=x64 +call "%EDGETX_BUILD_TOOLS%\.venv\Scripts\activate.bat" + +REM +REM start build +REM +cmake -G Ninja %BUILD_OPTIONS% %PATHS% %CMAKE_PREFIX_PATH% %LANGUAGE% %BUILD_TYPE% %EDGETX_REPO% + +if %BUILD_FW%=="yes" ( + ninja arm-none-eabi-configure + ninja -C arm-none-eabi firmware +) + +REM If building installer is requested, need to build Companion +if %BUILD_INSTALLER%=="yes" GOTO build_cpn +if %BUILD_CPN%=="yes" GOTO build_cpn + +REM else +GOTO exit_script + +:build_cpn +ninja native-configure +ninja -C native libsimulator +ninja -C native simulator +ninja -C native companion + +if %BUILD_INSTALLER%=="yes" ( + ninja -C native install + %QT_DIR%\bin\windeployqt --libdir native\_install\bin --plugindir native\_install\plugins --no-compiler-runtime --no-translations --release native + robocopy %QT_DIR%\bin\ native\_install\bin qt.conf + "%NSIS_EXE%" native/companion/companion.nsi +) + +REM The following is in order to be able to run companion and simulator binaries directly in build output folder +%QT_DIR%\bin\windeployqt --libdir native --plugindir native\plugins --no-compiler-runtime --no-translations --release native +copy %EDGETX_BUILD_TOOLS%\SDL2\lib\x64\SDL2.dll %EDGETX_MAIN_DIR%\%BUILD_FOLDER%\native\ + +REM +REM done +REM +:exit_script +call "%EDGETX_BUILD_TOOLS%\.venv\Scripts\deactivate.bat" +time /t +pause +``` + +### NSIS Windows installer creator + +Install the NSIS compiler from https://nsis.sourceforge.io/Download + + + +### Python package manager uv + +Open a command prompt and navigate to `C:\edgetx\build-tools`. + +Install Python package manager uv according to the installation instructions at: https://docs.astral.sh/uv/getting-started/installation/#__tabbed_1_2 + +### Python virtual environment + +Continue on the command prompt at `C:\edgetx\build-tools`: +``` +uv venv +uv pip install clang lz4 jinja2 pillow pyelftools aqtinstall pydantic +``` + +### Qt development framework + +Continue on the command prompt at `C:\edgetx\build-tools` to install Qt 6.9.0 into the Python virtual environment: +``` +mkdir Qt +cd Qt +call "C:\edgetx\build-tools\.venv\Scripts\activate.bat" +aqt install-qt windows desktop 6.9.0 win64_msvc2022_64 -m qtmultimedia qtserialport +call "C:\edgetx\build-tools\.venv\Scripts\deactivate.bat" +``` +Reboot your computer. + + +## Building + +### Fetch the EdgeTX project + +Open command prompt at `C:\edgetx` and clone the EdgeTX repo: +``` +git clone --recursive -b https://github.com/EdgeTX/edgetx.git +``` +where is the branch or tag you wish to use, e.g. `main` for the main development brach, or use a tag, if you wish to download a release version, such as `v3.0.1`. This will fetch the project into `C:\edgetx\edgetx`. + +### Target specific build script + +Create a radio specific build script, e.g. here for example for RadioMaster TX16s (create it e.g. as `C:\edgetx\build_tx16s.cmd`): + +``` +@echo off + +set EDGETX_MAIN_DIR=C:\edgetx +set EDGETX_REPO=C:\edgetx\edgetx +set EDGETX_BUILD_TOOLS=C:\edgetx\build-tools + +set BUILD_RADIO="TX16s" +set BUILD_OPTIONS="-DPCB=X10;-DPCBREV=TX16S" +set BUILD_LANGUAGE="EN" +set BUILD_DEBUG="no" +set BUILD_FW="yes" +set BUILD_CPN="yes" +set BUILD_INSTALLER="yes" + +call "%EDGETX_MAIN_DIR%\edgetx_build.cmd" +``` +and start it. + +After the build finishes, you can find the binaries under `C:\edgetx\build-output-` (firmware binary under subfolder `arm-none-eabi`, Companion and Simulator binaries together with simulator library under folder `native` and Companion installer under subfolder `native\companion`). +Note! Be sure to wipe the `C:\edgetx\build-output-` content every time you change the build options. + +See https://github.com/EdgeTX/edgetx/blob/main/tools/build-common.sh for BUILD_OPTIONS to use for various EdgeTX supported radios. Note that whereas the shell script at GitHub has spaces as delimeters between the keys, then in the Windows batch file, you neet to use semicolon as a delimeter. diff --git a/docs/contributing/getting-started-with-git.md b/docs/contributing/getting-started-with-git.md new file mode 100644 index 000000000..6ab1862ed --- /dev/null +++ b/docs/contributing/getting-started-with-git.md @@ -0,0 +1,20 @@ +# Getting Started with Git + +[Git](https://git-scm.com/) is a widely used version control system and a backbone for EdgeTX development. GitHub is an online service hosting Git repositories. It adds to Git further collaboration features, such as issue tracking, discussions, Wikis and more. + +Git supersedes earlier popular free version control systems, such as [CVS](http://cvs.nongnu.org/) and [Subversion](https://subversion.apache.org/). Git is known for it's performace, flexibility, wide acceptance and good code quality. But also for being complicated and harder to learn than many competitive products. To learn Git, you can find a brilliantly written and freely available book about Git: [Pro Git Book by Scott Chacon and Ben Straub](https://git-scm.com/book/en/v2) + +If you are new to Git, then consider minimally working through the following chapters to get started working with EdgeTX Git repository: + + * [Getting a Git Repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository) + * [Branches in a Nutshell](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) + * [Rebasing](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) + +You can work with Git and interact with the EdgeTX repository on GitHub via command line tools, but graphical tools make the interaction especially for novices so much more easier. If you are interested on graphical user interface tools for Git, have a look for example at: + + * [TortoiseGit](https://tortoisegit.org/) (Windows only, integrates into Windows Explorer) + * [Fork](https://git-fork.com/) (Mac & Windows) + * [Sublime Merge](https://www.sublimemerge.com/) (Linux, Mac & Windows - no time limit evaluation) + * [VSCode](https://code.visualstudio.com/) (Linux, Mac & Windows, code editor with basic built in Git integration - extendable with plugins like GitLens) + +You can find some pointers from a Git novice perspective, getting to know Git and working with EdgeTX repository, on the following page: [Workflow for GitHub Noobs](workflow-for-github-noobs.md) diff --git a/docs/contributing/some-git-commands.md b/docs/contributing/some-git-commands.md new file mode 100644 index 000000000..4037af8f6 --- /dev/null +++ b/docs/contributing/some-git-commands.md @@ -0,0 +1,94 @@ +# Git Command Reference + +## Quick checklist + +### Terminal commands + + ls - lists all of the folders + ls -la - lists all of the files + cd .. - returns one dir back + cd - enters a directory + . - just install in the current directory + +### On initial install + + git --version - checks the version of the installed locally git + git config --global user.name "Your Name" - sets up the name of the user + git config --global user.email "yourname@somemail.eu" - sets up the mail of the user + git config --list - lists all the git configurations + +### For help on commands + + git help (e.g. git help config) OR + git --help + +### For initializing the project + + git init - initializes the git repo in the current folder + touch .gitignore - creates a git ignore file + git status - check working tree - both on the git and on local + +### Add files + + git add -A - adds all of the files for commiting + remember - git status - to check the state of the repo + +### Remove files + + git reset - removes files to be commited + git reset somefile.js - removes somefile.js from the commit preparation + +### Committing + + git commit -m "This is the commit message" - -m is used to add message + +### Check log + + git log - renders commit ids, authors, dates + +### Clone a remote repo + + git clone + +### View info about the repo + + git remote -v - lists info about the repo + git branch -a - lists all of the branches + +### View changes + + git diff - shows the difference made in the files + +### Pull before push ALWAYS + + git pull origin master + +### THEN PUSH + + git push origin master - name of remote repo the branch that we push to + +### First time push of the branch + + git push -u origin - -u coordinates the two branches (local and on server) + +### Create a branch + + git branch + +### Checkout a branch + + git checkout + +### Merge a branch + + git checkout master + git pull origin master + git branch --merged - see which branches are merged + git merge + git push origin master + +### Delete a branch + + git branch -d - this deletes it locally!!! + git branch -a - check the repo branches + git push origin --delete - this deletes it from the repo! diff --git a/docs/contributing/workflow-for-github-noobs.md b/docs/contributing/workflow-for-github-noobs.md new file mode 100644 index 000000000..b783aaff9 --- /dev/null +++ b/docs/contributing/workflow-for-github-noobs.md @@ -0,0 +1,222 @@ +# Workflow for GitHub Noobs + +This guide is targeted for Ubuntu Linux users, who want to help testing EdgeTX firmware and or LUA scripts, but who have not yet found their way around Git and GitHub. + +# How does GitHub work + +EdgeTX project uses GitHub services e.g. for distributed version control and source code management functionalities. As an open-source project, the source code can be downloaded by everyone. Users can modify and augment the code and propose the changes as so called pull requests. But this page is not about the latter. Here, we will concentrate on getting EdgeTX code from GitHub, in order to compile and test it locally. +If you used the guide to get Ubuntu running on a Windows subsystem, or having another Ubuntu environment, and you followed the instructions to get the compile toolchain installed, then you have already installed the GIT software with it, so no actions there. + +# The workflow + +## Getting the code + +Well, if you followed the installations and first instructions to the letter, you already did the following things: + +* Created a folder for managing code in your personal /home/user directory (~) + +``` +mkdir ~/edgetx +cd ~/edgetx +``` + +* "Cloned" the code from the public repository + +``` +git clone --recursive -b main https://github.com/EdgeTX/edgetx.git edgetx-main +``` + + * Created a subfolder for the _main_ branch by doing the above (~/edgetx/edgetx-main) + +That's good! + +## Compiling + +I will list all the steps to compile the code into the firmware for on the radio, the full simulator, and companion. The goal is that we test things first in the simulator, and then on the physical radio. Saves a lot of hassle. + +### Preparation + +``` +cd ~/edgetx/edgetx-main +``` + +If it doesn't exist yet from a previous build session, create a build output folder: + +``` +mkdir build-output +``` + +Move to the build-output folder and start preparation of the CMAKE file (the file that contains the instructions to compile all stuff): + +``` +cd build-output +``` + +Don't forget to add the path for this session: + +``` +export PATH="~/edgetx/edgetx-main/radio/util:$PATH" +``` + +(You can add it to your environment permanently. Search google). +And then create the makefile in the right spot: + +``` +cd ~/edgetx/edgetx-main/build-output +cmake -DPCB=X10 -DPCBREV=TX16S -DDEFAULT_MODE=2 -DGVARS=YES -DPPM_UNIT=US -DHELI=NO -DLUA=YES -DINTERNAL_GPS=YES -DCMAKE_BUILD_TYPE=Debug ../ +``` + +Change the above to your preferences of course :). See _~/edgetx-main-cmake-options.txt_. + +### Compiling the firmware + +``` +make -j`nproc` firmware +``` + +The firmware created to load on your radio is _firmware.bin_. + +### Compiling Companion + +``` +cd ~/edgetx/edgetx-main/build-output +make -j`nproc` companion25 +``` + +To launch Companion, issue: `./companion25` +Do that first, to create at least ONE profile to be able to use the simulator. + +### Compiling the simulator + +Remember it will use the settings as prepared in the cmake command. + +``` +cd ~/edgetx/edgetx-main/build-output +make -j`nproc` libsimulator && make -j`nproc` simulator25 +``` + +### Compiling all in one go + +Set the path if you didn't do it yet + +``` +export PATH="~/edgetx/edgetx-main/radio/util:$PATH" +``` + +Do the rest + +``` +cd ~/edgetx/edgetx-main/build-output +cmake -DPCB=X10 -DPCBREV=TX16S -DDEFAULT_MODE=2 -DGVARS=YES -DPPM_UNIT=US -DHELI=NO -DLUA=YES -DINTERNAL_GPS=YES -DCMAKE_BUILD_TYPE=Debug ../ +make -j`nproc` firmware +make -j`nproc` companion25 +make -j`nproc` libsimulator +make -j`nproc` simulator25 + +``` + +## Running companion or the simulator + +### Preparation + +You will need to have some location for the SDCARD you are going to use for the simulation. I suggest to set up an SDCARD folder in your personal directory, and create a subfolder for all radio types. Yes, if you are going to test, it is good practice to not only test your own preferred radio, but to test at least one of each of the other versions. It is a courtesy to the developer and future users: + +``` +mkdir ~/SDCARD +cd ~/SDCARD + +wget https://github.com/EdgeTX/edgetx-sdcard/releases/download/latest/taranis-x7.zip +wget https://github.com/EdgeTX/edgetx-sdcard/releases/download/latest/taranis-x9.zip +wget https://github.com/EdgeTX/edgetx-sdcard/releases/download/latest/horus.zip +unzip -u taranis-x7.zip +unzip -u taranis-x9.zip +unzip -u horus.zip +rm *.zip + +``` + +### Running companion + +The companion is located in the build_output directory, so we run it with this command: + +``` +~/edgetx/edgetx-main/build-output/companion25 +``` + +Now when companion started, you need to go to settings/radio profiles and create at least one profile, with the created radio type selected. Also, in settings, set the SDcard path to your just downloaded and unzipped SDCard content, in this tutorial the Horus content. + +```` +/home/yourUserName/SDCARD/horus +```` + +If you have an existing .otx file, you can now load is at well :). + +### Running the simulator + +The simulator is located in the build_output directory as well, so we run it with this command: + +```` +~/edgetx/edgetx-main/build-output/simulator25 +```` + +Now when companion started, you created at least one profile, with the created radio type. +Select that profile, and start it up. + +## Doing testwork + +Now you have a running simulator, you can test your own models by opening your .otx file in the simulator. Be aware that the simulator will actually CHANGE that file, so better use copies only. If the simulator works correct, you can try using the firmware on the radio. +You can just copy the firmware you created to the SDCard of your radio, in the FIRMWARE folder. Then, when starting the radio in BOOTLOADER mode by pushing the horizontal trims to each other while starting the radio, you can select the new firmware, and install it. +Make sure you have backups if needed, and a correct firmware somewhere to be able to go back when necessary. + +### Reporting an issue + +Well, if you found any issue, please first check if it is not an existing issue on github. +[EdgeTX open issues](https://github.com/EdgeTX/edgetx/issues?q=is%3Aissue+is%3Aopen) + +You can then add your findings to the existing issues, making it easier to solve it (correctly). +Otherwise, create a new issue. +[new issue](https://github.com/EdgeTX/edgetx/issues/new/choose) +At least, mention the radio type and firmware version in your issue, as well as if it was the simulator or the physical radio that showed the bug, or both. + +### Updating your copy of the repo after a fix was pushed + +This is the part where all the work was done for. By having the possibility to compile yourself, you don't need to wait for the release candidates to help testing certain changes! +You can now update the code you cloned before at anytime to the latest version by the following command: + +```` +cd ~/edgetx/edgetx_main +git pull https://github.com/EdgeTX/edgetx.git +```` + +This video gives some useful tips: +[github tutorial](https://www.youtube.com/watch?v=HVsySz-h9r4) + +## Some tips for Windows adepts + +* You can start an explorer from Ubuntu, that will allow you to access the Ubuntu files safely from Windows. Simple type `explorer.exe` in Ubuntu. In the explorer you open from Ubuntu in Windows: +* The Ubuntu files are under `\\wsl$\Ubuntu-20.04\` +Pin it to you quick access list of locations!! there is a small pin in the start menu on explorer to do that. + +Make sure you know where you are in Ubuntu Linux: +* the terminal starts in your personal directory in Ubuntu, just one level below `/HOME`. So type `cd /HOME`, and then `dir`, and you can see where your personal files are for your Ubuntu user. +* The X-windows terminal starts in `/mnt/c/Windows/System32`. To switch quickly to your home directory type `cd /HOME` + +## Conclusion + +It is not that difficult when you got it al listed out to setup and compile your own stuff, test it, report it back, and redo the entire cycle. + +I hope others feel the same when using this guide. + +Next guide will be on documentation. + +# Open Point + +I am really a noob. That helps to prevent the obvious things from being forgotten to write down for other noobs. Like setting the path on every session before the compile, and other stupid simple things you do without thinking when you do things more often. + +In this workflow, we are NOT interested in keeping things up to date, correct, organized, from a coding perspective. + +It is meant to reload another branch or tag or version or whatever things there are on GitHub that need testing or documentation (new parts in the GUI for instance) with as little as possible actions. And without ruining any settings or references that are already created for the companion and or simulator that are probably stored when running in the build-output directory. + +What I am not understanding yet is how to test a certain pull request before it is part of the main branch. + +If someone could help out there, that would be great. diff --git a/docs/development/cli-commands.md b/docs/development/cli-commands.md new file mode 100644 index 000000000..aed1e21bb --- /dev/null +++ b/docs/development/cli-commands.md @@ -0,0 +1,65 @@ +# CLI Commands + +Summary of the commands available in CLI mode. + +## Always available commands + +| Function | Parameters (if any) | Description | +|--|--|--| +| `beep` |`[] []`| Play a beep sound. | +| `ls` | ``| List files in a directory. | +| `read` |`` | Read a file. | +| `readsd` |` `| Read sectors from SD card. | +| `testsd` | | Test SD card. | +| `play` | `` | Play a file. | +| `reboot` | `[wdt]` | Reboot the device. | +| `set` | ` ` | Set a configuration parameter. | +| `help` | `[]` | Show help for a command. | + +## If `ENABLE_SERIAL_PASSTHROUGH` set + +| Function | Parameters (if any) | Description | +|--|--|--| +| `serialpassthrough` | ` ` | Enable serial passthrough. | + + +## If `DEBUG` set + +| Function | Parameters (if any) | Description | +|--|--|--| +| `print` | `
[] \| ` | Print a value. | +| `p` | `
[] \| ` | Print a value. | +| `stackinfo` | | Show stack info. | +| `meminfo` | | Show memory info. | +| `test` | `new \| graphics \| memspd` | Run a test. | +| `trace` | `on \| off` | Enable/disable tracing. | +| `debugvars` | | Show debug variables. | +| `repeat` | ` ` | Repeat a command. | + + +## If `JITTER_MEASURE` set + +| Function | Parameters (if any) | Description | +|--|--|--| +| `jitter` | | Measure jitter. | + + +## If `INTERNAL_GPS` set + +| Function | Parameters (if any) | Description | +|--|--|--| +| `gps` | `\|$\|trace` | Send a command to the GPS. | + + +## If `BLUETOOTH` set + +| Function | Parameters (if any) | Description | +|--|--|--| +| `bt` | `\|` | Send a command to the Bluetooth module. | + + +## If `ACCESS_DENIED` && `DEBUG_CRYPT` set + +| Function | Parameters (if any) | Description | +|--|--|--| +| `crypt` | `` | Encrypt a string. | diff --git a/docs/development/control-inputs.md b/docs/development/control-inputs.md new file mode 100644 index 000000000..afff20d83 --- /dev/null +++ b/docs/development/control-inputs.md @@ -0,0 +1,122 @@ +# Control Inputs Refactor + +This page documents the concepts and ideas implemented in [#2631](https://github.com/EdgeTX/edgetx/pull/2631). + +## General + +In `YAML`, only canonical names are used. The UI uses however translated labels +that can be overridden with custom labels. + + +## Main Controls + +Sometimes called sticks, gimbals, wheel and throttle: whatever is used to control +the vehicle. + +To be able to implement the stick modes used usually in RC aircrafts, it is +necessary to map the physical controls to canonical labels. + +Canonical names shall be used for physical reference: +- calibration data, + +Canonical labels are used for logical references: +- inputs +- mixer lines +- etc + +Corresponding to the canonical labels, UI labels are used to present translated +names to the user. These UI labels can be overidden by the user by defining custom labels. + +### Physical main controls + +- Radios with 2 gimbals: + - `LH`: left gimbal, vertical axis + - `LV`: left gimbal, horizontal axis + - `RV`: right gimbal, vertical axis + - `RH`: right gimbal, horizontal axis + +- Surface radios: + - `WH`: steering wheel + - `TR`: throttle trigger + +### Canonical names + +- Radios with 2 gimbals: + - `Rud` + - `Ele` + - `Thr` + - `Ail` + +- Surface radios: + - `Whl` + - `Thr` + + +## Additional controls + +Additional analog controls have canonical names equal to the canonical labels. + +On top of these, labels can be defined to be used in the UI and thus correspond +to the real labels printed on the radio case on in the user manual. These labels can be +overidden by the user by defining custom labels. + +### Potentiometers, sliders, joystick + +Canonical / physical names: +- `P1`, `P2`, etc +- `SL1`, `SL2`, etc +- `JSx` and `JSy` + +### Switches + +Canonical names: +- `SA` to `SZ` + + +## APIs + +We use different APIs for the different types of names and labels. + +All APIs used the same types as follows: + +``` +enum { + ADC_INPUT_MAIN, + ADC_INPUT_POT, + ADC_INPUT_AXIS, + ADC_INPUT_VBAT, + ADC_INPUT_RTC_BAT +}; +``` + +### Physical names + +Physical names are manipulated by using the following functions: + +``` +const char* analogGetPhysicalName(uint8_t type, uint8_t idx); +int analogLookupPhysicalIdx(uint8_t type, const char* name, size_t len); +``` + +### Canonical names + +Canonical names are retrieved by using the following function: + +``` +const char* analogGetCanonicalName(uint8_t type, uint8_t idx); +int analogLookupCanonicalIdx(uint8_t type, const char* name, size_t len); +``` + +### UI labels + +UI labels are retrieved using the following functions: + +``` +# Retrievs the name of the input (custom or canonical) +const char* getAnalogLabel(uint8_t type, uint8_t idx); + +# Custom labels +void analogSetCustomLabel(uint8_t type, uint8_t idx, const char* str, size_t len); +const char* analogGetCustomLabel(uint8_t type, uint8_t idx); +bool analogHasCustomLabel(uint8_t type, uint8_t idx); +``` diff --git a/docs/development/customisable-switches.md b/docs/development/customisable-switches.md new file mode 100644 index 000000000..01500faae --- /dev/null +++ b/docs/development/customisable-switches.md @@ -0,0 +1,47 @@ +# Customisable Switches + +The functions switches are a type of multipos switches that are managed directly by EdgeTX. Physically, they look a bit like a regular 6pos switch, but they are much more flexible. + +Unlike other switches that are manage at radio level, functions switches are defined per model, and are therefore set in model setup page. + +## Switch type + +Function switch can be set to: + +`none` : they are basically disabled + +`toggle` : they are active only during push duration + +`2POS` : pushing the switch will alternate state : OFF push ON push OFF .... + +## Switch group + +A traditional 6POS is basically a group of 6 switches that work together, where only one can be active at one time. Functions switches expand that concept and let you choose how FS should be grouped. + +`-` defines a function switch with no group. Pushing it will only affect this switch + +`1`, `2` or `3` define groups. All the switches in a group act together, **where only one (the last pushed) can be active** + +**Always on groups** : in hardware 6POS implementations, one switch of the group MUST stay on, in other words, the switches in the group cannot be all off. If you want this type of behavior, you should tick the check box at the right side of the screen. + +In a traditional 6POS , all the switches belong to the same group. If you want 2 groups of 3 switches, assign 3 switches to group 1, and 3 to group 2 + +![Customisable switches figure 1](../assets/images/fs_fig1.png) + +## Startup Position + +For switch not in group, you can defined in what state each switches will be when the model is loaded + +`↑` switch is inactive + +`↓` switch is active + +`=` switch is set to the same state is was when the model was last used (it keeps old state) + +For groups + +`=` all switches in group are set to the same state is was when the model was last used (it keeps old state) + +`SWx` SWx is set to on, the others in groups are set to off + +`OFF` all switches are set to off at start (NOT available when group is set to 'always on') diff --git a/docs/development/external-module-protocols.md b/docs/development/external-module-protocols.md new file mode 100644 index 000000000..4505efa77 --- /dev/null +++ b/docs/development/external-module-protocols.md @@ -0,0 +1,37 @@ +# External Module Protocols + +# PPM + +![PPM protocol waveform](../assets/images/PPM.png) + +# PXX (FrSky XJT) + +![PXX protocol waveform](../assets/images/PXX.png) + +# ACCESS (FrSky RM900 ACCESS) + +![ACCESS protocol waveform](../assets/images/ACCESS.png) + +# DSM2 (Spektrum hacked module) + +125000 bauds 8N1 - No parity + +![DSM2 protocol waveform](../assets/images/DSM2.png) + +# SBUS (Normal mode) + +100000 bauds - Inverted - Even parity + +![SBUS Normal protocol waveform](../assets/images/SBUS%20Normal.png) + +# Multimodule + +100000 bauds - Even parity - 2 stops bit + +![MULTI protocol waveform](../assets/images/MULTI.png) + +# Crossfire + +400000 bauds (or reduced depending on radio capabilities) - Inverted + +![XFIRE protocol waveform](../assets/images/XFIRE.png) diff --git a/docs/development/mixer-synchronisation.md b/docs/development/mixer-synchronisation.md new file mode 100644 index 000000000..d7bc17646 --- /dev/null +++ b/docs/development/mixer-synchronisation.md @@ -0,0 +1,38 @@ +# Mixer Synchronisation + +The EdgeTX mixer can be synchronised with some modules. + +Here is a short list of synchronised modules/protocols: +- any module using `CRSF` (Crossfire, Tracer, ExpressLRS) +- `GHST` +- `MPM` +- PXX1 / PXX2 (based on FrSky's heartbeat mechanism) + +## Mixer task + +The mixer task is responsible for mainly 3 things: +- trigger the ADC conversions +- compute channel values +- send the channels to the module(s) + +## Mixer scheduler + +The mixer task is triggered cycle-by-cycle with the help of a scheduler controlled by a timer. This timer is either set to a fixed (non-synchronised modules) or an adjustable value. + +Synchronised modules are able to adjust the value of this timer by implementing a regulation loop that allows to optimise the timing for some metrics. Most of the time the module wants to optimise the latency. At the same time, it allows to prevent sampling aliasing caused by the ADC sample frequency being different from the frequency at which channels are sent over the air (historical reason for implementing the mixer scheduler in the first place). + +[![Mixer synchronisation diagram](../assets/images/mixersync.png)](../assets/images/mixersync.png) + +If we look at the regulation loop, there are indeed two parameters that you want to be able to set: +- frequency +- phase + +The mixer scheduler will take these two parameters as input to set the timer for the next cycle and try to adjust accordingly. + +## Regulation loop + +The synchronisation mechanism can be seen as a classical regulation loop. The set point in this regulation loop is the mixer scheduler timer. The feedback is given by the module to directly adjust the set point. Please note that the regulation is actually living in the module: this means that the module is responsible for adjusting the set point according to its needs (in most cases, minimising latency). + +## Heartbeat mechanism + +FrSky implements the synchronisation in a different way, so the mixer scheduler is by-passed. When a heartbeat is detected, the mixer is triggered and the safety timer is reset. diff --git a/docs/development/yaml-parser-generator.md b/docs/development/yaml-parser-generator.md new file mode 100644 index 000000000..b2f9748bf --- /dev/null +++ b/docs/development/yaml-parser-generator.md @@ -0,0 +1,275 @@ +# YAML Parser Generator + +The YAML storage used in EdgeTX since version `2.6` relies on the radio side on a parser +generator that creates a structure in flash memory to be used by the parser to +determine a precise mapping `attribute -> [bit address, bit length]`. + +This is done by using `libclang` Python bindings to parse `ModelData` and `RadioData` +as well as related structures to compute precise bit-offsets for each attribute. + +## Generating YAML parsers for existing radios + +As the Python script used only works for now with certain versions of libclang, +it is highly recommended to use the EdgeTX dev container to generate YAML parsers. + +The master script used will generate the parsers for all different radios: +```shell +docker run -it --rm -v $(pwd):/src \ + ghcr.io/edgetx/edgetx-dev \ + /src/tools/generate-yaml.sh +``` + +It is also possible to generate only for certain radios by using the `FLAVOR` variable: +```shell +docker run -it --rm -v $(pwd):/src \ + -e "FLAVOR=tx16s;x12s;nv14;x7;x9d;x9dp" + ghcr.io/edgetx/edgetx-dev \ + /src/tools/generate-yaml.sh +``` + +Please check `tools/generate-yaml.sh` for available target names. + +## Generating YAML parsers for new radios + +When new radios are integrated, it might be necessary to generate new YAML parser structures +if that new radio does not fit 100% to an existing one in terms of storage. + +In this case, a number of preparatory steps shall be taken: +- `radio/src/storage/yaml/CMakeLists.txt`: add the proper file name depending on radio + and naming conventions (use downcase target name as used in other scripts). +- `radio/src/storage/yaml/yaml_datastructs.cpp`: add the proper generated file depending + on the radio. + +New radios shall not add conversions routines from the old storage format. This means +that the `STORAGE_CONVERSIONS` variable should be set appriately to `221` (YAML format) +in `radio/src/storage/conversions/CMakeLists.txt`. + +This will effect that the conversion routines will be excluded from compilation. + + +## A word of caution on changing `RadioData` and `ModelData` structures + +The YAML parser generator does not account for padding bits added automatically by the +compiler. This means that great care should be taken to understand how these padding bits +are added when using bit fields. + +For example: +```c++ + NOBACKUP(uint8_t countryCode:2); + NOBACKUP(int8_t pwrOnSpeed:3); + NOBACKUP(int8_t pwrOffSpeed:3); +``` + +These fields define a bit field which fills the supporting `8-bit` type completely. If however +another field would be introduced, it could add padding bits *implicitely*. + +```c++ + NOBACKUP(uint8_t countryCode:2); + NOBACKUP(int8_t pwrOnSpeed:3); + NOBACKUP(int8_t pwrOffSpeed:3); + // New field + NOBACKUP(int8_t myField:2); +``` + +The new field `myField` here will introduce a new bit field spread on `8 bits` with only `2` +defined explicitly. The compiler however might introduce `6 padding bits` at the end, +depending on what is defined *after*. If the next attributes are also bit field members, the +padding bits will be added after the next bit field, and so on. + +If however a normal attribute is defined next, the padding bits will be added directly after +`myField`, and the parser generator will **not** account for them, so that a shift in the bit +address will be introduced and the complete structure will be broken. + +```c++ + NOBACKUP(uint8_t countryCode:2); + NOBACKUP(int8_t pwrOnSpeed:3); + NOBACKUP(int8_t pwrOffSpeed:3); + // New field + NOBACKUP(int8_t myField:2); + // Normal type + NOBACKUP(int8_t fullField); +``` + +In this case, silent padding bits shall be explicitly defined to avoid the issue: +```c++ + NOBACKUP(uint8_t countryCode:2); + NOBACKUP(int8_t pwrOnSpeed:3); + NOBACKUP(int8_t pwrOffSpeed:3); + // New field + NOBACKUP(int8_t myField:2); + NOBACKUP(int8_t paddingBits:6 SKIP); + // Normal type + NOBACKUP(int8_t fullField); +``` + +Here we use a special attribute `SKIP` to instruct the parser generator to ignore this field +but still account for it in the bit count. + +## Custom fields + +When a special behavior shall be implemented for certain attributes, custom functions +can be used to implement that behavior. + +This allows for covering the following use cases: +- custom input/output formats +- backward compatibility + +### Custom input/output formats + +Attributes that require a specific input or output format can use the `CUST()` macro. +This macro takes 2 parameters as follows: +- `read` function: used for reading YAML payload. +- `write` function: used for writing YAML payload. + +Example: +``` +NOBACKUP(int8_t beepVolume:4 CUST(r_5pos,w_5pos)); +``` + +Here the parser generator will assume that `r_5pos` and `w_5pos` are 2 existing functions, +with the following prototype: +```c++ +bool w_5pos(const YamlNode* node, uint32_t val, yaml_writer_func wf, void* opaque); +uint32_t r_5pos(const YamlNode* node, const char* val, uint8_t val_len); +``` + +### Full Custom Attributes + +Fully Custom Attributes are used when there is no direct relationship between a YAML tag +and a member of the data structure. It allows mainly for implementing complex logic +and backward compatibility. Backward compatibility is reached when using such an attribute +for which only the `read` function is defined, but no `write` function. + +Here is an example of such backward compatibility attributes: +``` + CUST_ATTR(auxSerialMode, r_serialMode, nullptr); + CUST_ATTR(aux2SerialMode, r_serialMode, nullptr); + NOBACKUP(uint16_t serialPort ARRAY(STORAGE_SERIAL_PORTS,struct_serialConfig,nullptr)); +``` + +Both `auxSerialMode` and `aux2SerialMode` are defined here right in front of the new +`serialPort` array to simplify offset calculations in the function setting the values. + +The same macro can also be used to implement `read`/`write` logic, as is used for +module configuration: +``` + CUST_ATTR(subType,r_modSubtype,w_modSubtype); + ... + uint8_t subType:4 SKIP; +``` + +Here the real `subType` attribute is marked `SKIP` so that it is ignored by the parser +generator, and a full custom attribute is used to set this attribute instead +(`CUST_ATTR(subType,r_modSubtype,w_modSubtype)`). This is done this way to allow for different +`enum` types depending on the module type. + +The custom functions `r_modSubtype` and `w_modSubtype` select the proper lookup table +depending on another attribute (`type`) in `ModuleData`, which is not possible otherwise. + +It allows also at the same time to map the MPM protocol numbers to the real ones (those +as defined in the MPM documentation), whereby EdgeTX use internally different protocol numbers +for historical reasons (special treatment of FrSky protocols). + +### Union members + +EdgeTX uses `union` extensively. This means however that the parser needs to know which +member to select / output when writing YAML. + +This is done by implementing a `selector`, for example as seen in the TelemetrySensor +structure: + +```c++ + union { + NOBACKUP(PACK(struct { + uint16_t ratio; + int16_t offset; + }) custom); + NOBACKUP(PACK(struct { + uint8_t source; + uint8_t index; + uint16_t spare SKIP; + }) cell); + NOBACKUP(PACK(struct { + int8_t sources[4]; + }) calc); + NOBACKUP(PACK(struct { + uint8_t source; + uint8_t spare[3] SKIP; + }) consumption); + NOBACKUP(PACK(struct { + uint8_t gps; + uint8_t alt; + uint16_t spare SKIP; + }) dist); + uint32_t param; + } NAME(cfg) FUNC(select_sensor_cfg); +``` + +The `TelemetrySensor` defines a anonymous `union`, which the `NAME(cfg)` macro gives a tag +name, while `FUNC(select_sensor_cfg)` defines the selector function. + +The `selector` function is then implemented as follows in `yaml_datastruct_funcs.cpp`: +```c++ +uint8_t select_sensor_cfg(void* user, uint8_t* data, uint32_t bitoffs) +{ + data += bitoffs >> 3UL; + data -= offsetof(TelemetrySensor, param); + const TelemetrySensor* sensor = (const TelemetrySensor*)data; + + if (sensor->unit < UNIT_FIRST_VIRTUAL) { + if (sensor->type == TELEM_TYPE_CALCULATED) { + switch(sensor->formula) { + case TELEM_FORMULA_CELL: return 1; // cell + case TELEM_FORMULA_DIST: return 4; // dist + case TELEM_FORMULA_CONSUMPTION: return 3; // consumption + case TELEM_FORMULA_TOTALIZE: return 3; // consumption + default: return 2; // calc + } + } else { + return 0; // custom + } + } + + return 5; +} +``` + +The function starts with computing the structure index to obtain a pointer and basically +returns an index which corresponds to which union member shall be used (as defined, +counting from `0`). + +### Forced `enum` type + +The parser generator uses member types as defined to determine what to generate. +However, some structure members are in fact `enum` types, whereby declared as `uint8_t` or +similar. + +So that these values can be output / read as their string representation, it is necessary +to specify the `enum` type that shall be used as follows: +```c++ +uint8_t func ENUM(LogicalSwitchesFunctions); +``` + +This will also force the parser generator to process that `enum` type in case it is not used +explictly (by type definition) somewhere else. + +This can also be used to force the generation of the lookup table even if the values are not +used directly: +```c++ +uint16_t srcRaw:10 ENUM(MixSources) CUST(r_mixSrcRaw,w_mixSrcRaw); +``` + +This will force the `enum` type to be considered for generation, whereby this specific +attribute will used custom functions. + +In this particular case the function can then make use of this lookup table as they see fit. + +For example with (reading): +``` +yaml_parse_enum(enum_MixSources, val, val_len); +``` + +Or (writing): +``` +str = yaml_output_enum(val, enum_MixSources); +``` diff --git a/docs/hardware/dma-mapping-nv14.md b/docs/hardware/dma-mapping-nv14.md new file mode 100644 index 000000000..6882984ee --- /dev/null +++ b/docs/hardware/dma-mapping-nv14.md @@ -0,0 +1,27 @@ +# DMA Mapping of NV14 + +## DMA1 + +| Peripheral requests | Stream 0 | Stream 1 | Stream 2 | Stream 3 | Stream 4 | Stream 5 | Stream 6 | Stream 7 | +| ------------------- | --------------------- | -------------------------------------- | ---------------------------------- | --------------------------- | --------------------------- | --------------- | ------------------------- | --------------------- | +| Channel 0 | SPI3\_RX | \- | SPI3\_RX | SPI2\_RX | SPI2\_TX | SPI3\_TX | \- | SPI3\_TX | +| Channel 1 | I2C1\_RX | \- | TIM7\_UP | \- | TIM7\_UP | I2C1\_RX | I2C1\_TX | I2C1\_TX | +| Channel 2 | TIM4\_CH1 | \- | I2S3\_EXT\_RX | TIM4\_CH2 | I2S2\_EXT\_TX | I2S3\_EXT\_TX | TIM4\_UP | TIM4\_CH3 | +| Channel 3 | I2S3\_EXT\_RX | TIM2\_UP
TIM2\_CH3 | I2C3\_RX | I2S2\_EXT\_RX | I2C3\_TX | TIM2\_CH1 | TIM2\_CH2
TIM2\_CH4 | TIM2\_UP
TIM2\_CH4 | +| Channel 4 | UART5\_RX | USART3\_RX | **UART4\_RX
(DIGITAL_GIMBALS)** | USART3\_TX | **UART4\_TX
(DIGITAL_GIMBALS)** | USART2\_RX | **USART2\_TX
(TELEMETRY)** | UART5\_TX | +| Channel 5 | UART8\_TX | **UART7\_TX
(INTMODULE)** | TIM3\_CH4
TIM3\_UP | UART7\_RX | TIM3\_CH1
TIM3\_TRIG | TIM3\_CH2 | UART8\_RX | TIM3\_CH3 | +| Channel 6 | TIM5\_CH3
TIM5\_UP | TIM5\_CH4
TIM5\_TRIG | TIM5\_CH1 | TIM5\_CH4
TIM5\_TRIG | TIM5\_CH2 | \- | TIM5\_UP | \- | +| Channel 7 | \- | TIM6\_UP | I2C2\_RX | I2C2\_RX | USART3\_TX | DAC1 | DAC2 | I2C2\_TX | + +## DMA2 + +| Peripheral requests | Stream 0 | Stream 1 | Stream 2 | Stream 3 | Stream 4 | Stream 5 | Stream 6 | Stream 7 | +| ------------------- | ---------- | -------------------- | ----------------------------------- | --------- | ------------------------------------ | ----------------------- | ----------------------------------- | ------------------------------------ | +| Channel 0 | ADC1 | SAI1\_A | TIM8\_CH1
TIM8\_CH2
TIM8\_CH3 | SAI1\_A | **ADC1** | SAI1\_B | TIM1\_CH1
TIM1\_CH2
TIM1\_CH3 | \- | +| Channel 1 | \- | DCMI | ADC2 | ADC2 | SAI1\_B | SPI6\_TX | SPI6\_RX | DCMI | +| Channel 2 | **ADC3** | ADC3 | \- | SPI5\_RX | SPI5\_TX | CRYP\_OUT | CRYP\_IN | HASH\_IN | +| Channel 3 | SPI1\_RX | \- | SPI1\_RX | SPI1\_TX | \- | SPI1\_TX | \- | \- | +| Channel 4 | SPI4\_RX | SPI4\_TX | USART1\_RX | **SDIO** | \- | USART1\_RX | SDIO | USART1\_TX | +| Channel 5 | \- | USART6\_RX | **USART6\_RX
(EXTMODULE)** | SPI4\_RX | SPI4\_TX | \- | USART6\_TX | **USART6\_TX
(EXTMODULE)** | +| Channel 6 | TIM1\_TRIG | TIM1\_CH1 | TIM1\_CH2 | TIM1\_CH1 | TIM1\_CH4
TIM1\_TRIG
TIM1\_COM | TIM1\_UP | TIM1\_CH3 | \- | +| Channel 7 | \- | TIM8\_UP | **TIM8\_CH1
(EXTMODULE)** | TIM8\_CH2 | TIM8\_CH3 | SPI5\_RX | SPI5\_TX | TIM8\_CH4
TIM8\_TRIG
TIM8\_COM | diff --git a/docs/hardware/dma-mapping-tx16s.md b/docs/hardware/dma-mapping-tx16s.md new file mode 100644 index 000000000..59449070c --- /dev/null +++ b/docs/hardware/dma-mapping-tx16s.md @@ -0,0 +1,27 @@ +# DMA Mapping of TX16S + +## DMA1 + +| Peripheral requests | Stream 0 | Stream 1 | Stream 2 | Stream 3 | Stream 4 | Stream 5 | Stream 6 | Stream 7 | +| ------------------- | --------------------- | -------------------------------------- | ---------------------------------- | --------------------------- | --------------------------- | --------------- | ------------------------- | --------------------- | +| Channel 0 | SPI3\_RX | \- | SPI3\_RX | SPI2\_RX | SPI2\_TX | SPI3\_TX | \- | SPI3\_TX | +| Channel 1 | I2C1\_RX | \- | TIM7\_UP | \- | TIM7\_UP | I2C1\_RX | I2C1\_TX | I2C1\_TX | +| Channel 2 | TIM4\_CH1 | \- | I2S3\_EXT\_RX | TIM4\_CH2 | I2S2\_EXT\_TX | I2S3\_EXT\_TX | TIM4\_UP | TIM4\_CH3 | +| Channel 3 | I2S3\_EXT\_RX | **TIM2\_UP
TIM2\_CH3
(ACCESS\_MOD)** | I2C3\_RX | I2S2\_EXT\_RX | I2C3\_TX | TIM2\_CH1 | TIM2\_CH2
TIM2\_CH4 | TIM2\_UP
TIM2\_CH4 | +| Channel 4 | UART5\_RX | USART3\_RX | UART4\_RX | **USART3\_TX
(ACCESS\_MOD)** | **UART4\_TX
(FLYSKY\_HALL)** | USART2\_RX | **USART2\_TX
(TELEMETRY)** | UART5\_TX | +| Channel 5 | UART8\_TX | UART7\_TX | **TIM3\_CH4
TIM3\_UP
(TRAINER)** | UART7\_RX | TIM3\_CH1
TIM3\_TRIG | TIM3\_CH2 | UART8\_RX | TIM3\_CH3 | +| Channel 6 | TIM5\_CH3
TIM5\_UP | TIM5\_CH4
TIM5\_TRIG | TIM5\_CH1 | TIM5\_CH4
TIM5\_TRIG | TIM5\_CH2 | \- | TIM5\_UP | \- | +| Channel 7 | \- | TIM6\_UP | I2C2\_RX | I2C2\_RX | USART3\_TX | **DAC1
(AUDIO)** | DAC2 | I2C2\_TX | + +## DMA2 + +| Peripheral requests | Stream 0 | Stream 1 | Stream 2 | Stream 3 | Stream 4 | Stream 5 | Stream 6 | Stream 7 | +| ------------------- | ---------- | -------------------- | ----------------------------------- | --------- | ------------------------------------ | ----------------------- | ----------------------------------- | ------------------------------------ | +| Channel 0 | ADC1 | SAI1\_A | TIM8\_CH1
TIM8\_CH2
TIM8\_CH3 | SAI1\_A | ADC1 | SAI1\_B | TIM1\_CH1
TIM1\_CH2
TIM1\_CH3 | \- | +| Channel 1 | \- | DCMI | ADC2 | ADC2 | SAI1\_B | SPI6\_TX | SPI6\_RX | DCMI | +| Channel 2 | **ADC3** | ADC3 | \- | SPI5\_RX | SPI5\_TX | CRYP\_OUT | CRYP\_IN | HASH\_IN | +| Channel 3 | SPI1\_RX | \- | SPI1\_RX | SPI1\_TX | \- | SPI1\_TX | \- | \- | +| Channel 4 | SPI4\_RX | SPI4\_TX | USART1\_RX | **SDIO** | \- | USART1\_RX | SDIO | **USART1\_TX
(INTMODULE)** | +| Channel 5 | \- | **USART6\_RX
(AUX2)** | USART6\_RX | SPI4\_RX | SPI4\_TX | \- | USART6\_TX | USART6\_TX | +| Channel 6 | TIM1\_TRIG | TIM1\_CH1 | TIM1\_CH2 | TIM1\_CH1 | TIM1\_CH4
TIM1\_TRIG
TIM1\_COM | **TIM1\_UP
(EXTMODULE)** | TIM1\_CH3 | \- | +| Channel 7 | \- | TIM8\_UP | TIM8\_CH1 | TIM8\_CH2 | TIM8\_CH3 | SPI5\_RX | SPI5\_TX | TIM8\_CH4
TIM8\_TRIG
TIM8\_COM | diff --git a/docs/hardware/irq-usage-tx16s.md b/docs/hardware/irq-usage-tx16s.md new file mode 100644 index 000000000..678d42743 --- /dev/null +++ b/docs/hardware/irq-usage-tx16s.md @@ -0,0 +1,125 @@ +# IRQ Usage of TX16S + +| IRQn | IRQ handler acronym | Used for | Priority | Prio Addr | Description | Address | +| ---- | ------------------------------------------------------------------ | --------------------- | -------- | ---------- | ------------------------------------------- | ---------- | +| 0 | WWDG_IRQHandler | - | - | 0xE000E400 | Window WatchDog | 0x00000040 | +| 1 | PVD_IRQHandler | - | - | 0xE000E401 | PVD through EXTI Line detection | 0x00000044 | +| 2 | TAMP_STAMP_IRQHandler | - | - | 0xE000E402 | Tamper and TimeStamps through the EXTI line | 0x00000048 | +| 3 | RTC_WKUP_IRQHandler | - | - | 0xE000E403 | RTC Wakeup through the EXTI line | 0x0000004C | +| 4 | FLASH_IRQHandler | - | - | 0xE000E404 | FLASH | 0x00000050 | +| 5 | RCC_IRQHandler | - | - | 0xE000E405 | RCC | 0x00000054 | +| 6 | EXTI0_IRQHandler | - | - | 0xE000E406 | EXTI Line0 | 0x00000058 | +| 7 | EXTI1_IRQHandler | - | - | 0xE000E407 | EXTI Line1 | 0x0000005C | +| 8 | **EXTI2_IRQHandler** | TOUCH_INT_EXTI | 9 | 0xE000E408 | EXTI Line2 | 0x00000060 | +| 9 | EXTI3_IRQHandler | - | - | 0xE000E409 | EXTI Line3 | 0x00000064 | +| 10 | EXTI4_IRQHandler | - | - | 0xE000E40A | EXTI Line4 | 0x00000068 | +| 11 | DMA1_Stream0_IRQHandler | - | - | 0xE000E40B | DMA1 Stream 0 | 0x0000006C | +| 12 | **DMA1_Stream1_IRQHandler
(only HARDWARE_EXTERNAL_ACCESS_MOD)** | EXTMODULE_TIMER_DMA | 7 | 0xE000E40C | DMA1 Stream 1 | 0x00000070 | +| 13 | DMA1_Stream2_IRQHandler | - | - | 0xE000E40D | DMA1 Stream 2 | 0x00000074 | +| 14 | DMA1_Stream3_IRQHandler | - | - | 0xE000E40E | DMA1 Stream 3 | 0x00000078 | +| 15 | **DMA1_Stream4_IRQHandler** | FLYSKY_HALL_TX_DMA | 7 | 0xE000E40F | DMA1 Stream 4 | 0x0000007C | +| 16 | **DMA1_Stream5_IRQHandler** | AUDIO_DMA | 7 | 0xE000E410 | DMA1 Stream 5 | 0x00000080 | +| 17 | **DMA1_Stream6_IRQHandler** | TELEMETRY_DMA_TX | 1 | 0xE000E411 | DMA1 Stream 6 | 0x00000084 | +| 18 | ADC_IRQHandler | - | - | 0xE000E412 | ADC1, ADC2 and ADC3s | 0x00000088 | +| 19 | CAN1_TX_IRQHandler | - | - | 0xE000E413 | CAN1 TX | 0x0000008C | +| 20 | CAN1_RX0_IRQHandler | - | - | 0xE000E414 | CAN1 RX0 | 0x00000090 | +| 21 | CAN1_RX1_IRQHandler | - | - | 0xE000E415 | CAN1 RX1 | 0x00000094 | +| 22 | CAN1_SCE_IRQHandler | - | - | 0xE000E416 | CAN1 SCE | 0x00000098 | +| 23 | **EXTI9_5_IRQHandler** | TELEMETRY_EXTI | 0 | 0xE000E417 | External Line[9:5]s | 0x0000009C | +| 24 | TIM1_BRK_TIM9_IRQHandler | - | - | 0xE000E418 | TIM1 Break and TIM9 | 0x000000A0 | +| 25 | TIM1_UP_TIM10_IRQHandler | - | - | 0xE000E419 | TIM1 Update and TIM10 | 0x000000A4 | +| 26 | **TIM1_TRG_COM_TIM11_IRQHandler** | TELEMETRY_TIMER | 0 | 0xE000E41A | TIM1 Trigger and Commutation and TIM11 | 0x000000A8 | +| 27 | **TIM1_CC_IRQHandler** | EXTMODULE_TIMER | 7 | 0xE000E41B | TIM1 Capture Compare | 0x000000AC | +| 28 | **TIM2_IRQHandler
(only HARDWARE_EXTERNAL_ACCESS_MOD)** | EXTMODULE_TIMER | 7 | 0xE000E41C | TIM2 | 0x000000B0 | +| 29 | **TIM3_IRQHandler** | TRAINER_TIMER | 7 | 0xE000E41D | TIM3 | 0x000000B4 | +| 30 | **TIM4_IRQHandler** | ROTARY_ENCODER_TIMER | 7 | 0xE000E41E | TIM4 | 0x000000B8 | +| 31 | I2C1_EV_IRQHandler | - | - | 0xE000E41F | I2C1 Event | 0x000000BC | +| 32 | I2C1_ER_IRQHandler | - | - | 0xE000E420 | I2C1 Error | 0x000000C0 | +| 33 | I2C2_EV_IRQHandler | - | - | 0xE000E421 | I2C2 Event | 0x000000C4 | +| 34 | I2C2_ER_IRQHandler | - | - | 0xE000E422 | I2C2 Error | 0x000000C8 | +| 35 | SPI1_IRQHandler | - | - | 0xE000E423 | SPI1 | 0x000000CC | +| 36 | SPI2_IRQHandler | - | - | 0xE000E424 | SPI2 | 0x000000D0 | +| 37 | **USART1_IRQHandler** | INTMODULE_USART | 6 | 0xE000E425 | USART1 | 0x000000D4 | +| 38 | **USART2_IRQHandler** | TELEMETRY_USART | 6 | 0xE000E426 | USART2 | 0x000000D8 | +| 39 | **USART3_IRQHandler** | AUX_SERIAL_USART
(EXTMODULE_USART with HARDWARE_EXTERNAL_ACCESS_MOD) | 7
(6 with HARDWARE_EXTERNAL_ACCESS_MOD) | 0xE000E427 | USART3 | 0x000000DC | +| 40 | **EXTI15_10_IRQHandler** | ROTARY_ENCODER_EXTI and INTMODULE_HEARTBEAT | rotaryEncoderInit() sets to 8, but is overridden by init_intmodule_heartbeat() to 5 | 0xE000E428 | External Line[15:10]s | 0x000000E0 | +| 41 | RTC_Alarm_IRQHandler | - | - | 0xE000E429 | RTC Alarm (A and B) through EXTI Line | 0x000000E4 | +| 42 | OTG_FS_WKUP_IRQHandler | - | - | 0xE000E42A | USB OTG FS Wakeup through EXTI line | 0x000000E8 | +| 43 | TIM8_BRK_TIM12_IRQHandler | - | - | 0xE000E42B | TIM8 Break and TIM12 | 0x000000EC | +| 44 | **TIM8_UP_TIM13_IRQHandler** | MIXER_SCHEDULER_TIMER | 5 | 0xE000E42C | TIM8 Update and TIM13 | 0x000000F0 | +| 45 | **TIM8_TRG_COM_TIM14_IRQHandler** | INTERRUPT_xMS | 4
(bootloader uses 0) | 0xE000E42D | TIM8 Trigger and Commutation and TIM14 | 0x000000F4 | +| 46 | TIM8_CC_IRQHandler | - | - | 0xE000E42E | TIM8 Capture Compare | 0x000000F8 | +| 47 | DMA1_Stream7_IRQHandler | - | - | 0xE000E42F | DMA1 Stream7 | 0x000000FC | +| 48 | FSMC_IRQHandler | - | - | 0xE000E430 | FSMC | 0x00000100 | +| 49 | **SDIO_IRQHandler** | SDIO | 0 | 0xE000E431 | SDIO | 0x00000104 | +| 50 | TIM5_IRQHandler | - | - | 0xE000E432 | TIM5 | 0x00000108 | +| 51 | SPI3_IRQHandler | - | - | 0xE000E433 | SPI3 | 0x0000010C | +| 52 | UART4_IRQHandler | - | - | 0xE000E434 | UART4 | 0x00000110 | +| 53 | UART5_IRQHandler | - | - | 0xE000E435 | UART5 | 0x00000114 | +| 54 | **TIM6_DAC_IRQHandler** | AUDIO_TIM | 7 | 0xE000E436 | TIM6 and DAC1&2 underrun errors | 0x00000118 | +| 55 | TIM7_IRQHandler | - | - | 0xE000E437 | TIM7 | 0x0000011C | +| 56 | DMA2_Stream0_IRQHandler | - | - | 0xE000E438 | DMA2 Stream 0 | 0x00000120 | +| 57 | DMA2_Stream1_IRQHandler | - | - | 0xE000E439 | DMA2 Stream 1 | 0x00000124 | +| 58 | DMA2_Stream2_IRQHandler | - | - | 0xE000E43A | DMA2 Stream 2 | 0x00000128 | +| 59 | **DMA2_Stream3_IRQHandler** | SD_SDIO_DMA | 1 | 0xE000E43B | DMA2 Stream 3 | 0x0000012C | +| 60 | DMA2_Stream4_IRQHandler | - | - | 0xE000E43C | DMA2 Stream 4 | 0x00000130 | +| 61 | ETH_IRQHandler | - | - | 0xE000E43D | Ethernet | 0x00000134 | +| 62 | ETH_WKUP_IRQHandler | - | - | 0xE000E43E | Ethernet Wakeup through EXTI line | 0x00000138 | +| 63 | CAN2_TX_IRQHandler | - | - | 0xE000E43F | CAN2 TX | 0x0000013C | +| 64 | CAN2_RX0_IRQHandler | - | - | 0xE000E440 | CAN2 RX0 | 0x00000140 | +| 65 | CAN2_RX1_IRQHandler | - | - | 0xE000E441 | CAN2 RX1 | 0x00000144 | +| 66 | CAN2_SCE_IRQHandler | - | - | 0xE000E442 | CAN2 SCE | 0x00000148 | +| 67 | **OTG_FS_IRQHandler** | OTG_FS (USB) | 11 | 0xE000E443 | USB OTG FS | 0x0000014C | +| 68 | **DMA2_Stream5_IRQHandler** | EXTMODULE_TIMER_DMA | 7 | 0xE000E444 | DMA2 Stream 5 | 0x00000150 | +| 69 | DMA2_Stream6_IRQHandler | - | - | 0xE000E445 | DMA2 Stream 6 | 0x00000154 | +| 70 | **DMA2_Stream7_IRQHandler** | INTMODULE_DMA | 7 | 0xE000E446 | DMA2 Stream 7 | 0x00000158 | +| 71 | **USART6_IRQHandler** | AUX2_SERIAL_USART
(optional GPS_USART and BT_USART) | 7
(GPS 9, BT 6) | 0xE000E447 | USART6 | 0x0000015C | +| 72 | I2C3_EV_IRQHandler | - | - | 0xE000E448 | I2C3 event | 0x00000160 | +| 73 | I2C3_ER_IRQHandler | - | - | 0xE000E449 | I2C3 error | 0x00000164 | +| 74 | OTG_HS_EP1_OUT_IRQHandler | - | - | 0xE000E44A | USB OTG HS End Point 1 Out | 0x00000168 | +| 75 | OTG_HS_EP1_IN_IRQHandler | - | - | 0xE000E44B | USB OTG HS End Point 1 In | 0x0000016C | +| 76 | OTG_HS_WKUP_IRQHandler | - | - | 0xE000E44C | USB OTG HS Wakeup through EXTI | 0x00000170 | +| 77 | OTG_HS_IRQHandler | - | - | 0xE000E44D | USB OTG HS | 0x00000174 | +| 78 | DCMI_IRQHandler | - | - | 0xE000E44E | DCMI | 0x00000178 | +| 79 | CRYP_IRQHandler | - | - | 0xE000E44F | CRYP crypto | 0x0000017C | +| 80 | HASH_RNG_IRQHandler | - | - | 0xE000E450 | Hash and Rng | 0x00000180 | +| 81 | FPU_IRQHandler | - | - | 0xE000E451 | FPU | 0x00000184 | +| 82 | UART7_IRQHandler | - | - | 0xE000E452 | UART7 | 0x00000188 | +| 83 | UART8_IRQHandler | - | - | 0xE000E453 | UART8 | 0x0000018C | +| 84 | SPI4_IRQHandler | - | - | 0xE000E454 | SPI4 | 0x00000190 | +| 85 | SPI5_IRQHandler | - | - | 0xE000E455 | SPI5 | 0x00000194 | +| 86 | SPI6_IRQHandler | - | - | 0xE000E456 | SPI6 | 0x00000198 | +| 87 | SAI1_IRQHandler | - | - | 0xE000E457 | SAI1 | 0x0000019C | +| 88 | **LTDC_IRQHandler** | LTDC | 4
(LCD_Init sets first to 7) | 0xE000E458 | LTDC | 0x000001A0 | +| 89 | LTDC_ER_IRQHandler | - | - | 0xE000E459 | LTDC error | 0x000001A4 | +| 90 | DMA2D_IRQHandler | - | - | 0xE000E45A | DMA2D | 0x000001A8 | + +All interrupt priorities higher than [configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY](https://github.com/EdgeTX/edgetx/blob/c5c142d38d2c3b5150180f43731182240a9ccbb2/radio/src/FreeRTOSConfig.h#L98-L102) must not call any FreeRTOS functions! +Note that on Cortex ARM architectures higher priorities have lower value. + +With an in-circuit-debugger, the read out on a TX16S with only internal module configured resulted in the following NVIC register readouts (all values as hex values): + +Interrupt enable state (NVIC_ISER) from 0xE000E100: +``` +00 01 03 60 E0 31 42 08 80 00 00 01 00 00 00 00 +00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 +``` + +Interrupt priority (NVIC_IPR) from 0xE000E400: +``` +00 00 00 00 00 00 00 00 90 00 00 00 00 00 00 00 +70 10 00 00 00 00 00 00 00 00 00 00 00 70 70 00 +00 00 00 00 00 60 60 70 50 00 00 00 50 40 00 00 +00 00 00 00 00 00 70 00 00 00 00 10 00 00 00 00 +00 00 00 00 00 00 00 70 00 00 00 00 00 00 00 00 +00 00 00 00 00 00 00 00 40 00 00 00 00 00 00 00 +00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 +00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 +00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 +00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 +00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 +00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 +00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 +00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 +00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 +``` diff --git a/docs/hardware/radio-specs.md b/docs/hardware/radio-specs.md new file mode 100644 index 000000000..e1d17db7b --- /dev/null +++ b/docs/hardware/radio-specs.md @@ -0,0 +1,3 @@ +# Radio Hardware Specifications for EdgeTX + +See: https://edgetx.org/Radio-hardware-specifications-for-EdgeTX/ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..cfae0f526 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,26 @@ +# EdgeTX Developer Documentation + +Welcome to the EdgeTX developer wiki! + +![EdgeTX Logo](assets/images/EdgeTX_logo.png) + +EdgeTX is an open-source firmware for RC radio transmitters. This documentation covers technical topics for developers and contributors: how to build EdgeTX from source, hardware reference material, hardware modification guides, and internal software architecture. + +## What's in this wiki + +- **Contributing** — Getting started with Git, the GitHub workflow, and a command reference for common Git operations. +- **Building EdgeTX** — Step-by-step build instructions for every supported platform (Linux, macOS, Windows, Docker, and GitHub CodeSpaces), plus a reference for all CMake compilation options. +- **Hardware Reference** — Radio hardware specifications, DMA mappings and IRQ usage tables for specific radios. +- **Hardware Mods** — Community hardware modification guides for FlySky gimbals, FRM303 module, PL18 / Paladin EV, NB4+, and radio recovery (unbricking). +- **Development** — Internal architecture documentation covering CLI commands, customisable switches, control inputs, external module protocols, YAML storage, and mixer synchronisation. + +## Quick links + +| Section | Description | +|---|---| +| [Contributing](contributing/getting-started-with-git.md) | Start here if you are new to Git or GitHub | +| [Building — CodeSpaces](building/codespaces.md) | Build in a web browser with no local setup | +| [Building — Linux (Ubuntu 24.04)](building/linux-ubuntu-24.04.md) | Recommended local build environment | +| [Building — Windows](building/windows.md) | Native Windows build using Visual Studio + Ninja | +| [Unbrick your radio](mods/unbrick.md) | Recover from a failed flash using STM32CubeProgrammer | +| [Radio Specifications](hardware/radio-specs.md) | Hardware specs for supported radios | diff --git a/docs/mods/flashing-flysky-pl18.md b/docs/mods/flashing-flysky-pl18.md new file mode 100644 index 000000000..5a9be3d90 --- /dev/null +++ b/docs/mods/flashing-flysky-pl18.md @@ -0,0 +1,94 @@ +# Flashing EdgeTX to Flysky PL18 or Paladin EV + +This page lists the recommended steps to install EdgeTX onto Flysky PL18 or Paladin EV radios. + +- [Preparatory steps](#preparatory-steps) +- [Backing up Flysky Bootloader](#backing-up-flysky-bootloader) +- [Flashing EdgeTX bootloader and firmware](#flashing-edgetx-bootloader-and-firmware) +- [Preparing internal SPI flash](#preparing-internal-spi-flash) +- [External RF module support](#external-rf-module-support) + +*** + +[![EdgeTX on PL18EV](../assets/images/hw/flysky-pl18/edgetx_pl18ev.jpg)](../assets/images/hw/flysky-pl18/edgetx_pl18ev.jpg) + +Please keep in mind that at present day, EdgeTX support for Flysky PL18 and Paladin EV radios is still in development - the upcoming v2.10 is scheduled to provide the first release. Use EdgeTX on PL18 or Paladin EV for testing purposes only at the moment. A lot of EdgeTX functionality is already successfully implemented for PL18 / Paladin EV, but not all. + +Due to PL18 and Paladin EV radio hardware differences, when compared to other EdgeTX supported radios, full EdgeTX experience, as known from other supported color screen radios, will not be possible with PL18 and Paladin EV, at least not without some hardware modifications. Factory PL18 and Paladin EV do not have a real-time-clock, an arbitrary sound output and an expandable storage, latter due to lack of a microSD card slot. PL18 and Paladin EV come with internal 8 MB SPI flash chip, where from factory, part of Flysky PL18 or Paladin EV firmware is stored. EdgeTX uses this memory chip as a microSD card substitute. Due to limited size of 8 MB, full EdgeTX SD card contents does not although fit into the internal memory. As arbitrary sound output is not possible anyhow, you can skip copying the chunky `\SOUNDS` SD card subfolder. + +**If you ever want to restore the original Flysky firmware to your PL18 or Paladin EV at a later date, it is crucial that you follow successfully the _Backing up Flysky Bootloader_ section.** As only, if the Flysky bootloader is restored to the radio, you can use Flysky Assistant Windows software to fully restore also the SPI flash content via Flysky online servers. + +## Preparatory steps + +* Remove the FRM301 RF-module for now. This module likely will never get official EdgeTX support due to proprietary API that Flysky desires to keep confidential. You can use [Flysky FJR2 JR-micro bay adapter](https://www.flysky-cn.com/b1700-specifications) to attach arbitrary JR micro bay RF-modules to the PL18 or Paladin EV instead. Alternatively, consider ExpressLRS firmware for the FRM301 (see [ExpressLRS pull-request #1811](https://github.com/ExpressLRS/ExpressLRS/pull/1811)) or see the section about supported [external RF modules](#external-rf-module-support) below. +* Fully charge the battery of your PL18 or Paladin EV before starting with the backup or the flashing steps below. +* Download and install the latest STM32CubeProgrammer, see for instructions: [Unbrick your radio](unbrick.md) (you need to make an account at ST to be able to download it). +* Peel off the left rubber handle on your PL18 or Paladin EV. That should reveal two hidden buttons. The top button is the Device-Firmware-Upgrade (DFU) button, the bottom button is the ultimate master power-off button and will be required to be pressed to exit the DFU mode. + +[![PL18 hidden buttons](../assets/images/hw/flysky-pl18/pl18_hidden_buttons.jpg)](../assets/images/hw/flysky-pl18/pl18_hidden_buttons.jpg) + +## Backing up Flysky Bootloader + +**This step is crucial, if you ever wish to return/restore back to Flysky factory firmware on your PL18 or Paladin EV.** + +* Make sure your PL18 / Paladin EV radio is powered off. Grab and attach a microUSB cable on the radio side only for now. Put the radio flat on the table. Next, press and hold the upper hidden button (DFU) down, while you attach the other end of the USB cable into the computer, where you previously installed the STM32CubeProgrammer software. This connects your PL18 / Paladin EV to your computer in DFU mode. +* You should have heard the typical sound from your computer, when you attach an USB device. Start STM32CubeProgrammer software. +* The STM32F429BIT6 microcontroller in the PL18/PL18EV should have been detected on the right side of the STM32CubeProgrammer screen under USB configuration as a USB with a number, typically USB1. Open the drop-down menu next to `Port` to check if you see USB1 listed there and then select it. Click the green `Connect` button on top right. + +![STM32CubeProgrammer connect](../assets/images/hw/flysky-pl18/stm32cb_connect.png) + +* You might be greeted with some seemingly random content, do not get alarmed - this is all perfectly fine and just showing some of the first bytes of memory that are currently saved on the microcontroller. Most importantly, check that the lower right corner now lists _Cortex-M4_ to the right of the field `CPU`. + +![STM32CubeProgrammer chip info](../assets/images/hw/flysky-pl18/stm32cb_chipinfo.png) + +* Next you will read out the STM32F4 flash memory of your radio. In Device memory tab, make sure Address is `0x08000000` (Explanation: `0x08000000` is the starting address of the flash memory on STM32F4 microcontrollers). Enter size: `0x200000` (instead of default `0x400`). (Explanation: `0x200000` is 2 MByte in hex, the size of STM32F429BIT6 internal flash). Click the blue `Read` button. It takes ca. 5 sec. to read the full flash from radio into your computer. + +[![STM32CubeProgrammer read](../assets/images/hw/flysky-pl18/stm32cb_read.png)](../assets/images/hw/flysky-pl18/stm32cb_read.png) + +* Click the drop-down arrow on Read command and pick `Save-As`. + +![STM32CubeProgrammer save as](../assets/images/hw/flysky-pl18/stm32cb_saveas.png) + +* Give it a name, such as `PL18_factory.bin` and save it somewhere safe. This file is your ticket back to Flysky firmware on your radio, if you ever wish to restore your operating system. Check that the file is 2 MByte in size, if not - something went wrong and do NOT continue until you are able to sort it out. +* If you plan to continue flashing the EdgeTX bootloader and firmware next, skip all the following steps of this section, otherwise be sure to continue - as your radio will drain the battery otherwise. +* Click the green `Disconnect` button on top right of STM32CubeProgrammer. +* Eject the radio from your operating system, similarly as you would safely disconnect an USB stick. +* Disconnect the USB cable from the radio. +* Press briefly the bottom hidden button (this resets the power circuitry inside PL18 / Paladin EV and powers it down). + +## Flashing EdgeTX bootloader and firmware + +If your radio is already connected successfully in DFU mode to your computer, you can skip the first two steps below. + +* Make sure your PL18 / Paladin EV is powered down, before you continue. Take a microUSB cable. Attach it on the radio side only for now. Put the radio flat on the table. Next, press and hold the upper hidden button (DFU) down while you attach the other end of the USB cable into the computer with STM32CubeProgrammer installed. This connects your radio in DFU mode to the computer. +* You should have heard the typical sound from your computer, when you attach an USB device. +* Open [EdgeTX Buddy](https://buddy.edgetx.org/) with a Chromium-based webbrowser. +* Unfold `Filter` and check to list the pre-releases. Select `nigthly` as Firmware version and pick either `Flysky PL18` or `Flysky PL18EV` according to your radio. +* Press `Flash over USB` and wait for the flashing to end. **This process takes typically ca. 2 minutes to complete.** +* Disconnect the USB cable from the radio. +* Press briefly the bottom hidden button (this resets the power circuitry inside the radio and powers it down). + +## Preparing internal SPI flash + +* Make sure your PL18 / Paladin EV is powered down. Pull both horizontal trims (TR7 and TR8) together and press both power buttons to start into EdgeTX bootloader that you can hopefully see. If nothing happens, wait at least 3 minutes. + +[![EdgeTX bootloader on PL18](../assets/images/hw/flysky-pl18/edgetx_bootloader_pl18.jpg)](../assets/images/hw/flysky-pl18/edgetx_bootloader_pl18.jpg) + +* If EdgeTX bootloader started successfully, select erase internal flash (second option from the top). You navigate up/down with TR6 and select Exit/Enter with TR4. + +[![PL18 bootloader keys](../assets/images/hw/flysky-pl18/pl18_bootloader_keys.jpg)](../assets/images/hw/flysky-pl18/pl18_bootloader_keys.jpg) + +* The flash erase can take some minutes to complete. Wait and then turn off the radio using the power buttons. + +* Enter EdgeTX bootloader again and attach USB cable again. This time a drive should pop up on your computer. This is the 8 MB SPI flash re-purposed as a mini-storage. The first time you attach the radio to your computer, you might be prompted to format it - accept and format the SPI flash with FAT filesystem. As soon as the FAT file system has been successfully created on the SPI flash, you can start filling it, as you would normally fill EdgeTX content onto a SD card (use the [c480x320.zip](https://github.com/EdgeTX/edgetx-sdcard/releases) of the SD card repository). Remember that you only have 8 MB available, and by default you will have no audio output (without the mod), thus best you skip filling the SOUNDS. + +* Reboot the radio. You should be greeted with EdgeTX. Run the analogs calibration - be sure to calibrate the sticks, but also the pots and side sliders. PL18 and Paladin EV are touch-screen radios - for navigation around the user interface, please use the touch screen. + +# External RF module support + +The following external RF-modules have been successfully tested: + +1. External [ExpressLRS](https://www.expresslrs.org/) (ELRS) modules in micro-JR bay form factor using the [Flysky FJR2 adapter](https://www.flysky-cn.com/b1700-specifications) +2. [External MPM in micro-JR bay form factor](https://www.multi-module.org/basics/module-hardware#external-modules) using the [Flysky FJR2 adapter](https://www.flysky-cn.com/b1700-specifications) +3. [Flysky FRM303 RF-module](https://www.flysky-cn.com/frm303description) +4. Do-It-Yourself (DIY) 4-in-1 Multi-Protocol-Module (MPM) in FRM301 form factor. More information about this open source module can be found under: https://github.com/pascallanger/DIY-Multiprotocol-TX-Module/tree/master/STM32%20PCB/Flysky%20PL18 diff --git a/docs/mods/flysky-frm303-tx16s.md b/docs/mods/flysky-frm303-tx16s.md new file mode 100644 index 000000000..80ec35c83 --- /dev/null +++ b/docs/mods/flysky-frm303-tx16s.md @@ -0,0 +1,17 @@ +# Instructions for Installing FlySky FRM303 External Module to TX16S + +The modification is quite simple, similar to Access MOD but no need the inverter. + +Just need to reconnect the AUX1 output to PPM and Heartbeat pin directly. The following image shows how this can be done, I used connection plugs so that I can easily convert back to original circuit. + +Please note that this mod will only affect the functionality of the external module, the internal module is not affected, so that one can use the internal 4 in 1 and external FRM303 together. After the mod, the ELRS external module should still works as well, as the ELRS ext module will only use the S.Port pin, but other modules that make use of the PPM pin may not work anymore after this mod. + +![FRM303 wiring diagram](https://user-images.githubusercontent.com/18414861/230327856-c516c5e4-8fd8-41b4-b466-74912a5bfe6d.jpg) + +For FRM303 setup, you need to first select the 1.5M opensource protocol, please refer to FRM303 manual for the procedures. + +For radio settings, you need to setup AUX1 for External Module and then select Flysky in model settings, then everything done. Enjoy. + +![FRM303 radio settings 1](https://user-images.githubusercontent.com/18414861/230498165-be66dcf3-adb1-4e14-a2a6-28d3630c5181.png) + +![FRM303 radio settings 2](https://user-images.githubusercontent.com/18414861/230498177-42701d86-6335-4f65-9685-c36592fc1818.png) diff --git a/docs/mods/flysky-hall-sticks.md b/docs/mods/flysky-hall-sticks.md new file mode 100644 index 000000000..fa842bb03 --- /dev/null +++ b/docs/mods/flysky-hall-sticks.md @@ -0,0 +1,133 @@ +# Instructions for Installing FlySky Digital Hall Gimbals in EdgeTX Radios + +- [Mechanical mounting](#mechanical-mounting) +- [Electrical wiring](#electrical-wiring) + * [RadioMaster and Eachine TX16S](#radiomaster-and-eachine-tx16s) + * [Jumper T16 and T18](#jumper-t16-and-t18) + * [Jumper T20](#jumper-t20) + +*** + +FlySky [FS-HZCZ03-ADJ](https://www.flysky-cn.com/hzczspecifications) is a high quality digital hall-effect gimbal set that can be integrated into numerous EdgeTX supported radios. The gimbals feel very solid due to CNC milled aluminum parts. + +The position sensing of the gimbal axes is based on [Melexis MLX90393](https://www.melexis.com/en/product/MLX90393/Triaxis-Micropower-Magnetometer) Triaxis magnetometer. This hall-effect sensor IC uses digital SPI interface to output 16-bit values, proportional to the magnetic flux density sensed along the X, Y, and Z axes. + +The gimbal set employs two MLX90393 sensors, one for each stick. The SPI signals are routed to a microcontroller in the circuit board that provides a firmware that transform the 3D signal from the sensors to 4 channels output with 16-bits precision each. The transformation algorithm will combine the 3D signal with factory calibrated settings to ensure the channel outputs are linear and without temperature drifts. + +The channel outputs are sent to the radio transmitter via UART serial communication with 921.6 kbps transfer speed to ensure minimum latency. The sticks have a resolution of ca. 4500 discretization levels per gimbal axis. + +The code includes an automatic detection of FlySky digital hall gimbals on power-up of TX16S/T16/T18 radios and no special build-time option is required. If after initial 70 ms the FlySky gimbals are not detected, the code reverts to sampling analog sticks. + +## Mechanical mounting + +The original author of FlySky digital gimbal support in EdgeTX, Richard Li, developed in addition a mechanical adapter ring set to easily mount the FlySky digital hall gimbals to various radios: TX16S, T16, T18 and TX18S. He donated the design to his friend at Hawk-RC, who's business was greatly impacted COVID-19. If you are planning to integrate the gimbals into the radio, Richard kindly asks you to consider purchasing the adapter ring set from Hawk-RC: + +[TX16/18/16S/18S M.O.D FLYSKY Hall Sensor Assembly Kit](http://www.hawk-creation.com/index.php?route=product/product&product_id=6862) + +The adapter ring set comes with 4 plastic parts and a cable. First, the thicker set of plastic rings are mounted into the radio, using the 4 original gimbal screws: + +[![HawkRC TX16S adapter set step 1](../assets/images/hw/flysky-mod/HawkRC_TX16S_adapter_set_step1.jpg)](../assets/images/hw/flysky-mod/HawkRC_TX16S_adapter_set_step1.jpg) + +The adapter ring set is a perfect fit for RadioMaster and Eachine TX16S. For T16/T18 and TX18S, a small plastic protrusion needs to be removed first - for further details, please see the [Hawk-RC product page](http://www.hawk-creation.com/index.php?route=product/product&product_id=6862). + +In a second step, the thinner adapter rings are mounted on top, with two M2x6 screws each: + +[![HawkRC TX16S adapter set step 2](../assets/images/hw/flysky-mod/HawkRC_TX16S_adapter_set_step2.jpg)](../assets/images/hw/flysky-mod/HawkRC_TX16S_adapter_set_step2.jpg) + +In a third step, the FlySky gimbals are mounted using two M2x6 screws (outside) and two M2x14 screws (inside) each onto the adapter rings. And finally, the included cable needs to be attached to the left gimbal connector on the TX16S mainboard, circled green on next image: + +[![TX16S FlySky gimbal connection](../assets/images/hw/flysky-mod/TX16S_FlySky_gimbal_connection.jpg)](../assets/images/hw/flysky-mod/TX16S_FlySky_gimbal_connection.jpg) + +## Electrical wiring + +### RadioMaster and Eachine TX16S + +Two options of hooking up the FlySky digital hall gimbals to TX16S will be presented below - the first option is simpler and requires no soldering, but will cause slight ripple on the analog power rail. The second option does not use analog power rail to supply the electronics of FlySky gimbals, but will require soldering. The second option is highly recommended, as this will not inject the digital noise from the gimbals into the analog rail of the radio. + +#### Powering gimbal from the analog power rail + +With this option, the FlySky gimbals will be powered from the 3.3V analog rail, provided on the gimbal plug, making the wiring easy. All you need to do is to make a 4 wires cable to connect the Flysky Hall Stick to a gimbal plug and the firmware mod will works. Do note that this option, although more easy to wire, will cause some noise to your radio analogs - pots, sliders and also audio. + +The plug required for the gimbal is a 4P [JST ZH](https://www.jst-mfg.com/product/detail_e.php?series=287) 1.5mm plug as shown in the following figure: + +[![Gimbal Plug](../assets/images/hw/flysky-mod/GimbalPlug.png)](../assets/images/hw/flysky-mod/GimbalPlug.png) + +The plug required for the PCB of TX16S is a 6P [Molex Picoblade](https://www.molex.com/molex/products/part-detail/crimp_housings/0510210600) 1.25mm plug as shown in the following figure: + +[![TX16S PCB Plug](../assets/images/hw/flysky-mod/TX16S-PCBPlug.png)](../assets/images/hw/flysky-mod/TX16S-PCBPlug.png) + +After installation the TX16S is shown in the following figure: + +[![TX16S Install](../assets/images/hw/flysky-mod/TX16S-Install.jpg)](../assets/images/hw/flysky-mod/TX16S-Install.jpg) + +#### Powering the gimbals from the digital power rail + +The preferred way of powering FlySky digital hall gimbals on TX16S is from digital +3.3V power rail. This requires either soldering a JST PH 4-pin socket onto TX16S mainboard (recommended) or soldering the gimbal hookup wires directly to the mainboard. Hookup plan: + +[![TX16S better FlySky gimbal hookup](../assets/images/hw/flysky-mod/TX16S_better_FlySky_gimbal_hookup.jpg)](../assets/images/hw/flysky-mod/TX16S_better_FlySky_gimbal_hookup.jpg) + + +The final outcome with FlySky FS-HZCZ03-ADJ on RadioMaster TX16S Max: + +[![TX16S Outlook](../assets/images/hw/flysky-mod/TX16S-Outlook.jpg)](../assets/images/hw/flysky-mod/TX16S-Outlook.jpg) + +Another example, showing the usage of FlySky Paladin EV gimbals with TX16S and EdgeTX: + +[![FlySky Paladin EV gimbals on RM TX16S](../assets/images/hw/flysky-mod/FlySky_Paladin_EV_gimbals_on_RM_TX16S.jpg)](../assets/images/hw/flysky-mod/FlySky_Paladin_EV_gimbals_on_RM_TX16S.jpg) + +EdgeTX includes extended channel support for X10 family radios (this includes T16, TX16S, T18, TX18S) in the form of EX3 and EX4 inputs at right analog stick connector together with Flysky digital hall gimbals. EX3 and EX4 can be used, in addition to EX1 and EX2, to connect e.g. the Paladin EV gimbal stick end pots and stick end switches. Here the hookup of stick ends shown in detail: + +[![FlySky Paladin EV gimbals on RM TX16S hookup](../assets/images/hw/flysky-mod/FlySky_Paladin_EV_gimbals_on_RM_TX16S_hookup.jpg)](../assets/images/hw/flysky-mod/FlySky_Paladin_EV_gimbals_on_RM_TX16S_hookup.jpg) + +### Jumper T16 and T18 + +The T16/T18 gimbals use 3V for A/D conversion, and it should work as per the specifications of the gimbal. + +### Boxer + +The boxer mod support starts from EdgeTX 2.9.0. + +The connector is similar to the TX16S mod, just need to swap the TX and RX. +![Boxer connector diagram](https://user-images.githubusercontent.com/18414861/230499231-cde2ce32-3261-4ddf-93a6-fb3fb3677dab.png) + +Installation of Flysky digital hall gimbals into RadioMaster Boxer, using the [Hawk-RC Adapter ring set](http://www.hawk-creation.com/index.php?route=product/product&product_id=6862): + +Step 1: mounting the bottom rings using stock RadioMaster analog gimbal screws: +![Boxer step 1](https://user-images.githubusercontent.com/21011587/218251013-cab53a3a-a27a-4347-9a67-1407f7646909.png) + +Step 2: mounting top rings using 2x2 M2x6 screws: +![Boxer step 2](https://user-images.githubusercontent.com/21011587/218251059-7a00ca66-dfb9-495c-968f-661e11544faf.png) + +Step 3: mounting Flysky digital hall gimbals HZCZ03-ADJ (here HCZC03 from an EL18) with 2x2 M2x6 and 2x2 M2x14 screws to the adapter rings and attaching the gimbal connection cable: +![Boxer step 3](https://user-images.githubusercontent.com/21011587/218251138-e698dd56-5664-4ffa-ba04-6ee223be3382.png) + +Do note that the RX and TX lines of the gimbal connection cable need to be swapped for Boxer, when compared with T16/TX16S/T18 cable, that comes with Hawk-RC adapter rings. + +Here a close-up of the correct cable for Boxer - note especially the white (Gimbal RX) and yellow (Gimbal TX) data lines: +![Boxer cable close-up](https://user-images.githubusercontent.com/21011587/218251207-9879c298-0d79-4a22-af82-326ca607fac9.png) + +Further, please do note that on Boxer, the UART4 serial connection for digital gimbals is on the right gimbal header (when radio is looked from the back, then left side, as in the above picture), whereas on T16/TX16S/T18 the digital gimbals need to be connected to the left gimbal header. + +End-result: +![Boxer end result](https://user-images.githubusercontent.com/21011587/218251232-83de7b71-a490-4ff1-960b-eb3ebdd20063.png) + +### Jumper T20 + +To mod Jumper T20 with Flysky gimbals, you can use the same 3D printing kit for TX16S, however you may need to cut the plastic rods in the casing, the corners of the 3D printing kit and the corners of the gimbals as well in order to fit in the T20. + +Step 1: Remove the filtering caps, Jumper T20 uses 100nF caps for gimbal noise filtering, this will affect the serial communication for the flysky mod, so the cap need to be removed (2 caps marked as red in the following photo): +![T20 step 1](https://github.com/EdgeTX/edgetx/assets/18414861/7b91d12e-02db-40b9-ad79-b97a2a4913c6) + +Step 2: Cut the casing plastic rods and corners of 3d print kit and gimbal, only a little cut is necessary showing in the following photo: +![T20 step 2](https://github.com/EdgeTX/edgetx/assets/18414861/da61b2be-1ac5-4091-9368-155d0b74796f) + +Step 3: Wiring, you need to make a wire to connect the gimbal to the main PCB using the pin outs marked in the following photo: +![T20 step 3](https://github.com/EdgeTX/edgetx/assets/18414861/8f3535db-5546-4bf1-800c-739b3c3a7aa5) + +Step 4: Put everything back together, and done! +![T20 step 4](https://github.com/EdgeTX/edgetx/assets/18414861/5f907d1c-ea46-4144-8414-c14353092305) + +### Frsky X9D+ 2019 + +The mod for X9D+ 2019 is contributed by a user in China, he open-sourced what he did in the following link: +https://github.com/HIT-bangbang/Flysky-Hall-Sticks-Mod-for-X9D2019 diff --git a/docs/mods/flysky-nb4plus.md b/docs/mods/flysky-nb4plus.md new file mode 100644 index 000000000..1da4ecec1 --- /dev/null +++ b/docs/mods/flysky-nb4plus.md @@ -0,0 +1,39 @@ +# Flysky NB4+ Hardware Mod for Complete EdgeTX Support + +With some hardware modifications, it is possible to run a full featured EdgeTX firmware on Flysky NB4+ radio. Natively, these radios have the following limitations with EdgeTX: + +1. Similar to PL18/PL18EV, NB4+ has limited internal memory that is not big enough to carry a full SD card content. It comes with a 8 MByte sized NOR flash chip, which is sufficient for EdgeTX configuration files, but not for a full EdgeTX experience. +2. Similar to PL18/PL18EV, NB4+ cannot keep by default the date and the time. The internal printed circuit boards are prepared for real-time-clock functionality, but there are a few components are not populated by default. For this reason, RTC functionality will not work properly with EdgeTX out of the box. + +Below you can find step-by-step tips of how to modify your NB4+ to overcome the above mentioned problems. Be aware that warranty will be most certainly lost when following the modification steps listed here. + +### Step 1: Install RTC battery and upgrade the flash chip + +Open up your radio and take out the MCU main PCB that is located right under the LCD display. The MCU PCB is shown here: + +![NB4+ MCU PCB 1](https://github.com/EdgeTX/edgetx/assets/18414861/6b7e2acb-927a-4666-a22b-b08dd9593537) + +The BLUE SQUARE denotes the NOR flash chip. The factory chip populated is of type W25Q64JV (8MB in size) and is not big enough to fit all required files of the EdgeTX SD card content. You can replace it with MX25L25645G that has the same form factor and pinout, but is 32MB in size. Thus, desolder the W25Q64JV and replace it with MX25L25645G. Be sure to orient the IC the same way when resoldering (match pin 1 location). Besides the choice of a 32MB flash chip, the chips that uses a WSON8 packaging can fit for replacement as well. However this packaging is better soldered using a hot blower instead of a soldering iron and can be an option to those who are skillful enough. Both W25Q512JV (64MB) and W25Q01JV (128MB) NOR flash chips are supported. + +The RED SQUARE denotes the location of the RTC battery. This can be populated with MS-621 rechargeable battery. Please note that after installation, it needs some time for it to charge up, before RTC functionality starts to work properly. + +In order to have the RTC working properly, only adding the RTC battery is not enough. When you flip the PCB to the other side, there are some components missing for RTC to work properly: + +![NB4+ MCU PCB 2](https://github.com/EdgeTX/edgetx/assets/18414861/f95e841d-2730-4adc-b06d-a730ab5716df) + +The RED SQUARE denotes the location of the RTC clocking circuit, you need to solder a 32kHz crystal and 2 x 3.9pF capacitors in this location. The YELLOW SQUARE denotes the location of a diode that enable the charging of the RTC battery, just solder a LL4148 diode will works. The BLUE SQUARE denotes the location of 2 capacitors: 100nF and 10pF. You may refer to the following schematic for details about the RTC battery design. + +![RTC Battery Schematic](https://github.com/EdgeTX/edgetx/assets/18414861/33363d9e-4c77-45ec-ba77-4a56fb3ddafa) + +### Step 2: Flash EdgeTX + +The following link provides instructions to flash EdgeTX to PL18/PL18EV: +[Flashing EdgeTX to Flysky PL18 or Paladin-EV](flashing-flysky-pl18.md) + +Flashing NB4+ uses the same procedure, only differences are the location of DFU and hard power off buttons: + +![NB4+ DFU button](https://github.com/user-attachments/assets/675c7877-ecf7-4015-b642-c5c2ff8b6c5c) + +![NB4+ hard power off button](https://github.com/user-attachments/assets/ee5157b3-d38d-4321-a556-a9f2e4f7da8b) + +I am still working a way to have usable TX modules with NB4+, stay tune and wait for my update. diff --git a/docs/mods/flysky-pl18.md b/docs/mods/flysky-pl18.md new file mode 100644 index 000000000..17c33db20 --- /dev/null +++ b/docs/mods/flysky-pl18.md @@ -0,0 +1,54 @@ +# Flysky PL18 & PL18EV Hardware Mod for Complete EdgeTX Support + +With some hardware modifications, it is possible to run a full featured EdgeTX firmware on Flysky PL18 and Paladin EV radios. Natively, these radios have the following limitations with EdgeTX: + +1. PL18/PL18EV have limited internal memory that is not big enough to carry a full SD card content. PL18/PL18EV do not have an option to expand the internal memory with a microSD card. Internally, these radios carry a 8 MByte sized NOR flash chip, which is sufficient for EdgeTX configuration files, but not for a full EdgeTX experience. For example, the std. English sound pack w/o explicit script sounds, needs already ca. 26 MBytes. +2. PL18/PL18EV cannot output arbitrary sounds. Instead they use a dedicated sound chip with factory pre-programmed sounds. And it is also not easily possible to reprogram this chip, e.g. using a software only solution. +3. PL18/PL18EV cannot keep by default the date and the time. PL18 and PL18EV internal printed circuit boards are prepared for real-time-clock functionality, but the required battery is not populated by default. For this reason, RTC functionality will not work properly with EdgeTX out of the box. + +Below you can find step-by-step tips of how to modify your PL18/PL18EV to overcome the above mentioned problems. Be aware that warranty will be most certainly lost when following the modification steps listed here. + +Craig at WTF RC Cars has created a nice video, visually explaining the hardware modification steps (click on the picture below to open the video): + +[![Video of the steps](https://i.ytimg.com/vi/r_UN9fZ-rDw/hqdefault.jpg)](https://www.youtube.com/watch?v=r_UN9fZ-rDw "Edge TX PL18 hardware mods RTC battery. Sound and memory upgrade.") + +### Step 1: Install RTC battery and upgrade the flash chip + +Open up your radio and take out the MCU main PCB that is located right under the LCD display. The MCU PCB is shown here: + +![PL18 MCU PCB](https://github.com/EdgeTX/edgetx/assets/18414861/61dfcc52-7f3c-4c79-8f01-d59529d38598) + +The RED CIRCLE denotes the location of the RTC battery. This can be populated with MS-621 rechargeable battery. Please note that after installation, it needs some time for it to charge up, before RTC functionality starts to work properly. + +The BLUE SQUARE denotes the NOR flash chip. The factory chip populated is of type W25Q64JV (8MB in size) and is not big enough to fit all required files of the EdgeTX SD card content. You can replace it with MX25L25645G that has the same form factor and pinout, but is 32MB in size. Thus, desolder the W25Q64JV and replace it with MX25L25645G. Be sure to orient the IC the same way when resoldering (match pin 1 location). + +(Updated 2023-10-07) We discovered that the chips that uses WSON8 packaging can fit for replacement as well. However this packaging is better soldered using a hot blower instead of a soldering iron and can be an option to those who are skillful enough. And the latest branch supports W25Q512JV (64MB) and W25Q01JV (128MB) NOR flash chips as well. + +### Step 2: Mod for DAC sound output + +This modification reroutes the sound generation directly to the main STM32F4 microcontroller, bypassing the original factory pre-programmed audio chip. This way arbitrary sounds can be output via EdgeTX firmware. The modification is carried out on the PCB in the lower part of the radio. As a first step, disconnect the output of the sound chip to the audio amplifier by de-soldering the capacitor marked with a RED CIRCLE in the following image: + +![Capacitor from audio chip to audio amplifier](https://github.com/EdgeTX/edgetx/assets/18414861/36de6855-ff27-41fc-ba94-75742f4fbf2a) + +As a second step, wire up the DAC output to the sound amplifier input via a capacitor as shown below: + +![DAC connection to audio amplifier](https://github.com/EdgeTX/edgetx/assets/18414861/5defa6ad-ba4d-4da8-9fe7-61e7c69ca7aa) + +### Step 3: Flash EdgeTX + +The following link provides instructions to flash EdgeTX to PL18/PL18EV: +[Flashing EdgeTX to Flysky PL18 or Paladin-EV](flashing-flysky-pl18.md) + +### Step 4: (PL18EV Only) Reroute stick ends + +Since we have used one of the stick ends buttons for DAC audio output, the original stick ends output need to be rerouted to the RX of UART7. +![Reroute stick end buttons](https://github.com/EdgeTX/edgetx/assets/18414861/591c2c8e-9a5d-4fa4-9d14-2070635d90bf) + + +### Step 5: (Optional PL18 Only) Install an internal Multi-Protocol Module (MPM) + +There exists an open sourced design of an internal 4-in-1 Multi-Protocol-Module (MPM) for Flysky PL18, please see for more details: https://github.com/richardclli/DIY-PL18-InternalMPM + +![PL18 Internal MPM](https://github.com/richardclli/DIY-PL18-InternalMPM/blob/main/images/ModuleInstall.jpg) + +Have Fun!!! diff --git a/docs/mods/unbrick.md b/docs/mods/unbrick.md new file mode 100644 index 000000000..27f74e4f5 --- /dev/null +++ b/docs/mods/unbrick.md @@ -0,0 +1,72 @@ +# Unbrick Your Radio + +In case you ever need to recover from a bodged flashing, the following steps will lead you back to working radio by cleanly re-flashing the bootloader and the firmware in one go. + +John at RCVideoReviews has created a nice video, visually explaining the steps of this page: + +[![Video of the steps explained on this page](../assets/images/flashing/rcvr_yt_unbrick.jpg)](https://www.youtube.com/watch?v=H9_sxXY_K-8 "RCVR: How-to UNBRICK Radiomaster TX16s ZORRO TX12 BOXER") + +1. Download and install a copy of STM32CubeProgrammer, the official flashing tool by ST, the manufacturer of the microcontrollers in EdgeTX radios. Get it here: +[https://www.st.com/en/development-tools/stm32cubeprog.html](https://www.st.com/en/development-tools/stm32cubeprog.html) + +During the installation of STM32CubeProgrammer, make sure your radio is not connected to your computer. + +The benefit of using STM32CubeProgrammer, instead of numerous other tools, is that it comes with reliably working Device Firmware Upgrade (DFU) drivers, required to perform the recovery of the radio. This has shown to be especially critical on Microsoft Windows operating systems. DFU is a hardware feature of the STM32 chips (the main microcontrollers in EdgeTX radios) that cannot be altered, erased or otherwise tampered with, thus it is always there and will allow you to easily recover from flashing mishaps. + +You might be requested to make an account at ST to be able to download STM32CubeProgrammer. + +2. Next, grab yourself a correct EdgeTX binary file to flash your radio with. You can use for example [EdgeTX Flasher](https://github.com/EdgeTX/flasher/releases) or directly browse to [EdgeTX GitHub](https://github.com/EdgeTX/edgetx/releases) page to fetch a binary of your choice. Save the binary on your local drive in a location you can easily find it. + +3. Connect your radio via USB to your PC while your radio is turned off. In case your radio has multiple USB ports, make sure you are using the data USB port and not the charging port. For example, on popular RadioMaster TX16S, you should use the top USB-C port next to the antenna. Make sure your USB cable is equipped also with data pins. Some more simpler USB cables only have power pins for charging, but the data pins for communication are not wired up. Such cables won't unfortunately work for radio recovery. + +4. Start STM32CubeProgrammer. Your radio should be detected on the right side of the screen under `USB configuration` as a `USB` with a number, typically `USB1`. Open the drop-down menu next to `Port` to see if you see `USB1` listed there and can select it. Below is an image how it should look like (you can click on the images to open them bigger): + +[![STM32CubeProgrammer step 1](../assets/images/flashing/STM32CubeProgrammer_01.png)](../assets/images/flashing/STM32CubeProgrammer_01.png) + +If the _Port_ drop-down box lists `No DFU`, then please re-check your cabling and try with another USB port on your PC. When reconnecting your radio to the computer, make sure the radio is still turned off. + +If you hear a bling sound from your system, when connecting an USB device, such as an USB stick, then the same sound should be emitted, when you connect your radio in DFU mode to your computer. + +5. Click the green `Connect` button on top right. You might be greeted with some seemingly random content, do not get alarmed - this is all perfectly fine and just showing some of the first bytes of memory that are currently saved on the microcontroller. Most importantly, the lower right corner should now list under field `CPU` either `Cortex-M3` or `Cortex-M4` (according to your radio): + +[![STM32CubeProgrammer step 2](../assets/images/flashing/STM32CubeProgrammer_02.png)](../assets/images/flashing/STM32CubeProgrammer_02.png) + +6. Next we load the EdgeTX binary into STM32CubeProgrammer. For this, first let's open the left menu fully, by clicking the button with three white horizontal bars on top left. After clicking it, the menu should open and the 3 bars become vertical bars: + +[![STM32CubeProgrammer step 3](../assets/images/flashing/STM32CubeProgrammer_03.png)](../assets/images/flashing/STM32CubeProgrammer_03.png) + +Click `Erasing & programming` (a green icon, with a down arrow and a flat rectangular shaped device under it). + +7. Next, click blue `Browse` button behind _File path_ field and navigate and open the previously downloaded EdgeTX binary for your radio. Leave `Verify programming` selected and make sure `Run after programming` is not selected: + +[![STM32CubeProgrammer step 4](../assets/images/flashing/STM32CubeProgrammer_04.png)](../assets/images/flashing/STM32CubeProgrammer_04.png) + +The instructions here ask to uncheck the `Run after programming` in order to avoid a warning dialog that would otherwise pop up at the end of flashing, when the code in the radio's microcontroller starts and the radio abruptly self-disconnects from STM32CubeProgrammer. + +8. Click the blue button `Start Programm...` in the middle of the STM32CubeProgrammer. + +First you should see some messages about erasing sectors and the green progress bar will go back and forth between left and right. This should be followed by a `Download in Progress` notification with green progress bar at the bottom of the STM32CubeProgrammer growing from left to right: + +[![STM32CubeProgrammer step 5](../assets/images/flashing/STM32CubeProgrammer_05.png)](../assets/images/flashing/STM32CubeProgrammer_05.png) + +Especially on bigger color radios with chunky microcontrollers, the flashing can take some minutes. Please be patient and wait for the STM32CubeProgrammer to do it's thing. + +9. When flashing has completed, you should be greeted with `File download complete` pop-up: + +[![STM32CubeProgrammer step 6](../assets/images/flashing/STM32CubeProgrammer_06.png)](../assets/images/flashing/STM32CubeProgrammer_06.png) + +followed briefly thereafter with `Download verified successfully` pop-up: + +[![STM32CubeProgrammer step 7](../assets/images/flashing/STM32CubeProgrammer_07.png)](../assets/images/flashing/STM32CubeProgrammer_07.png) + +In case you are only seeing the latter pop-up, then it is likely just covering the `File download complete` pop-up, that is underneath it. Click `OK` on both pop-ups to dismiss them. + +10. Click the green `Disconnect` button on top right of STM32CubeProgrammer. + +11. Eject the radio from your operating system, similarly as you would safely disconnect an USB stick (typically the radio is listed in DFU mode as `STM32 BOOTLOADER`). + +You can now remove the USB cable from your radio and power it up. + +You should be greeted with EdgeTX running on your radio again. + +![EdgeTX logo](../assets/images/EdgeTX_logo.png) diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..59188b26c --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,108 @@ +site_name: EdgeTX Developer Documentation +site_url: https://docs.edgetx.org/ +repo_url: https://github.com/EdgeTX/edgetx +repo_name: EdgeTX/edgetx +edit_uri: edit/main/docs/ + +theme: + name: material + logo: assets/images/EdgeTX_logo.png + favicon: assets/images/EdgeTX_logo.png + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: custom + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: custom + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - navigation.tabs + - navigation.tabs.sticky + - navigation.sections + - navigation.expand + - navigation.top + - search.suggest + - search.highlight + - content.code.copy + - content.action.edit + +markdown_extensions: + - admonition + - pymdownx.details + - pymdownx.superfences + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.tabbed: + alternate_style: true + - tables + - attr_list + - md_in_html + - toc: + permalink: true + +nav: + - Home: index.md + - Contributing: + - Getting Started with Git: contributing/getting-started-with-git.md + - Workflow for GitHub Noobs: contributing/workflow-for-github-noobs.md + - Git Command Reference: contributing/some-git-commands.md + - Building EdgeTX: + - Overview: building/index.md + - In a Web Browser (CodeSpaces): building/codespaces.md + - Windows: building/windows.md + - Windows (Docker): building/windows-docker.md + - Linux (Ubuntu 22.04): building/linux-ubuntu-22.04.md + - Linux (Ubuntu 24.04): building/linux-ubuntu-24.04.md + - Linux (WSL / Ubuntu 20.04): building/linux-wsl.md + - macOS (Sequoia / Tahoe): building/macos-sequoia.md + - macOS (Sonoma): building/macos-sonoma.md + - macOS (Catalina): building/macos-catalina.md + - Compilation Options: building/compilation-options.md + - Qt Creator (Obsolete): building/qt-creator.md + - Hardware Reference: + - Radio Specifications: hardware/radio-specs.md + - DMA Mappings: + - RadioMaster TX16S: hardware/dma-mapping-tx16s.md + - FlySky NV14: hardware/dma-mapping-nv14.md + - IRQ Usage: + - RadioMaster TX16S: hardware/irq-usage-tx16s.md + - Hardware Mods: + - Flysky Hall Sticks: mods/flysky-hall-sticks.md + - Flysky FRM303 Mod for TX16S: mods/flysky-frm303-tx16s.md + - Flysky PL18 & PL18EV: mods/flysky-pl18.md + - Flysky NB4+: mods/flysky-nb4plus.md + - Flashing EdgeTX to Flysky PL18/Paladin-EV: mods/flashing-flysky-pl18.md + - Unbrick Your Radio: mods/unbrick.md + - Development: + - CLI Commands: development/cli-commands.md + - Customisable Switches: development/customisable-switches.md + - Control Inputs: development/control-inputs.md + - External Module Protocols: development/external-module-protocols.md + - YAML Parser/Generator: development/yaml-parser-generator.md + - Mixer Synchronisation: development/mixer-synchronisation.md + +extra_css: + - assets/stylesheets/extra.css + +plugins: + - search + - minify: + minify_html: true + +extra: + version: + provider: mike + alias: true + social: + - icon: fontawesome/brands/github + link: https://github.com/EdgeTX/edgetx + - icon: fontawesome/brands/discord + link: https://discord.gg/wF9wUKnZ6H