From 7373f54c8a5d36981ce04cbe41bccd318fde58af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Niccol=C3=B2=20Betto?= <niccolo.betto@skywarder.eu> Date: Tue, 5 Dec 2023 11:59:41 +0100 Subject: [PATCH] [README] Improve wording, update outdated information. --- README.md | 52 +++++++++++++++++++++++++++------------------------- 1 file changed, 27 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 00eb37bf3..9ccf881ae 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,43 @@ <div align="center"> - <img src="https://avatars2.githubusercontent.com/u/8077370?s=200&v=4" alt="Skyward" width="200"></a> -<h2>Skyward Boardcore</h2> + <img src="https://avatars2.githubusercontent.com/u/8077370?s=200&v=4" alt="Skyward Experimental Rocketry" width="200"></a> +<h1>Skyward Boardcore</h1> <a href="https://git.skywarder.eu/avn/swd/skyward-boardcore/-/pipelines"><img src="https://git.skywarder.eu/avn/swd/skyward-boardcore/badges/main/pipeline.svg"></a> </div> -Boardcore is a framework for developing and building rockets software for custom boards with Miosix. +Boardcore is a C++14 rocket software framework targeting custom embedded boards designed by Skyward Experimental Rocketry. -[Miosix](https://miosix.org/) is a lightweight OS for embedded developing which provides support for basic things such as Threads, GPIO, Time and many other. You can find our fork of the kernel here: [skyward/miosix-kernel](https://git.skywarder.eu/avn/swd/miosix-kernel) +Boardcore runs on top of [Miosix](https://miosix.org/), a lightweight operating system for microcontrollers. It implements a POSIX-like API, the C standard library and the C++ standard library. It also provides a pre-emptive scheduler (among others) and a custom concurrency API with support for Threads and synchronization primitives. +A FAT32 filesystem, a serial port driver, platform timers and General Purpose I/O functionalities (GPIO) are also exposed through a custom API. -Building is made with [SBS](https://git.skywarder.eu/avn/swd/skyward-boardcore/wikis/Skyward-Build-System-(SBS)), which was created to easily compile and reuse code for different boards. +We maintain a fork of the Miosix OS to fit our needs: [skyward/miosix-kernel](https://git.skywarder.eu/avn/swd/miosix-kernel) + +The project is built with the CMake build system. We also have our own script that is built on top of CMake, to automate compilation and deployment to different hardware targets, [SBS](https://git.skywarder.eu/avn/swd/skyward-boardcore/wikis/Skyward-Build-System-(SBS)). ## Content | Path | Description | | ---------------- | ----------------------------------------------------------- | -| src/shared/ | Objects, drivers and other stuff written by us | -| src/entrypoints/ | Each file here is a 'main' | -| src/tests/ | Contains the 'main' of every test | -| build/ | Compiled binaries that can be flashed on a target board | -| libs/ | External libs (Miosix kernel and others as a git submodule) | -| scripts/ | Some tools (e.g. script for flashing on the boards) | - -In the main folder you will find **CMakeLists.txt** which is used to configure the build system. +| src/bsps/ | Board Support Packages (BSP) | +| src/shared/ | Device drivers and general-purpose classes/utilities | +| src/entrypoints/ | Entry points for general tasks (e.g. calibration) | +| src/tests/ | Entry points for on-device unit testing | +| build/ | Build output directory | +| libs/ | External libraries (git submodules) | +| scripts/ | Various tools and utilities (e.g. linting, log decoder) | ## Getting Started ### Dependencies -* CMake -* Git -* Miosix Toolchain +* `CMake` 3.25 +* `Git` +* `Miosix` Toolchain -Also, Ccache, Ninja, OpenOCD, Cppcheck, clang-format and pre-commit are recommended for a better experience. +We also recommend to install `Ccache`, `Ninja`, `OpenOCD`, `Cppcheck`,`ClangFormat` and `pre-commit` for a smoother development experience. ### Cloning the repo -Clone this repo with the `--recursive` option. +Clone the repository with the `--recursive` option: ```sh git clone --recursive https://git.skywarder.eu/avn/swd/skyward-boardcore.git cd skyward-boardcore @@ -43,14 +45,14 @@ cd skyward-boardcore ## Building -You can build everything using the SBS script: +Using the SBS script is the recommended way to build the project. When called with no arguments, it will build all targets: ```sh ./sbs ``` -The build system will start building all the targets (entrypoints and tests). Depending on how many targets there are, this operation may take several minutes. If you installed ccache, subsequent runs will be much faster. +This may take a while depending on how many targets there are. If `ccache` is installed, it will be used to cache intermediate compilation artifacts to speed-up incremental builds. -Or you can use directly CMake: +Alternatively, you can build with CMake commands: ```sh mkdir build cd build @@ -60,7 +62,7 @@ cmake --build . ## Documentation -The code is documented with Doxygen, check it [here](http://avn.pages.skywarder.eu/swd/skyward-boardcore). +The code is documented with Doxygen, check it out [here](http://avn.pages.skywarder.eu/swd/skyward-boardcore). ## Contributing @@ -72,8 +74,8 @@ pre-commit install ## What's next? -In the [Wiki](https://git.skywarder.eu/avn/swd/skyward-boardcore/wikis/home) you will find some first-steps **guides** (configuring the IDE, building a firmware, etc.) as well as the **coding guidelines** and some **best practices** we adopt. +You can find first-step **guides** in the [Wiki](https://git.skywarder.eu/avn/swd/skyward-boardcore/wikis/home) (configuring the IDE, building examples, etc.) as well our **code guidelines** and **best practices** that we follow. -If you want to contribute to this repository, please read [Git Workflow](https://git.skywarder.eu/avn/swd/skyward-boardcore/wikis/Git-Workflow). +If you want to contribute to this repository, please read our [Git Workflow](https://git.skywarder.eu/avn/swd/skyward-boardcore/wikis/Git-Workflow). -If you just want to start messing around, try [this](https://git.skywarder.eu/avn/swd/skyward-boardcore/-/wikis/LED-Blink). +If you want to start messing around with the code, check out the [LED blink guide](https://git.skywarder.eu/avn/swd/skyward-boardcore/-/wikis/LED-Blink). -- GitLab