diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 7e178df6..13459099 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,5 +1,6 @@ * xref:getting_started.adoc[Getting started] ** xref:basic_application.adoc[Basic application] +** xref:project_structure.adoc[Project Structure] * xref:layer_by_layer.adoc[Bare metal to async] * xref:runtime.adoc[Executor] * xref:hal.adoc[HAL] diff --git a/docs/modules/ROOT/pages/faq.adoc b/docs/modules/ROOT/pages/faq.adoc index 2d49b68a..2994c627 100644 --- a/docs/modules/ROOT/pages/faq.adoc +++ b/docs/modules/ROOT/pages/faq.adoc @@ -4,87 +4,6 @@ These are a list of unsorted, commonly asked questions and answers. Please feel free to add items to link:https://github.com/embassy-rs/embassy/edit/main/docs/modules/ROOT/pages/faq.adoc[this page], especially if someone in the chat answered a question for you! -== How do I even start? - -There are many ways to configure embassy and it's components for your exact application. The link:https://github.com/embassy-rs/embassy/tree/main/examples[examples] directory for each chipset demonstrate how your project structure should look. Let's break it down: - -The toplevel file structure of your project should look like this: -[source,plain] ----- -{} = Maybe - -my-project -|- .cargo -| |- config.toml -|- src -| |- main.rs -|- build.rs -|- Cargo.toml -|- {memory.x} -|- rust-toolchain.toml ----- - -=== .cargo/config.toml - -This directory/file describes what platform you're on, and configures link:https://github.com/probe-rs/probe-rs[probe-rs] to deploy to your device. - -Here is a minimal example: - -[source,toml] ----- -[target.thumbv6m-none-eabi] # <-change for your platform -runner = 'probe-rs run --chip STM32F031K6Tx' # <- change for your chip - -[build] -target = "thumbv6m-none-eabi" # <-change for your platform - -[env] -DEFMT_LOG = "trace" # <- can change to info, warn, or error ----- - -=== build.rs - -This is the build script for your project. It links defmt (what is defmt?) and the `memory.x` file if need be. This file is pretty specific for each chipset, just copy and paste from the corresponding link:https://github.com/embassy-rs/embassy/tree/main/examples[example]. - -=== Cargo.toml - -This is your manifest file, where you can configure all of the embassy components to use the features you need. - -TODO: someone should exhaustively describe every feature for every component! - -=== memory.x - -This file outlines the flash/ram usage of your program. It is especially useful when using link:https://github.com/embassy-rs/nrf-softdevice[nrf-softdevice] on an nRF5x. - -Here is an example for using S140 with an nRF52840: - -[source,x] ----- -MEMORY -{ - /* NOTE 1 K = 1 KiBi = 1024 bytes */ - /* These values correspond to the NRF52840 with Softdevices S140 7.0.1 */ - FLASH : ORIGIN = 0x00027000, LENGTH = 868K - RAM : ORIGIN = 0x20020000, LENGTH = 128K -} ----- - -=== rust-toolchain.toml - -This file configures the rust version and configuration to use. - -A minimal example: - -[source,toml] ----- -[toolchain] -channel = "nightly-2023-08-19" # <- as of writing, this is the exact rust version embassy uses -components = [ "rust-src", "rustfmt" ] # <- optionally add "llvm-tools-preview" for some extra features like "cargo size" -targets = [ - "thumbv6m-none-eabi" # <-change for your platform -] ----- - == How to deploy to RP2040 without a debugging probe. Install link:https://github.com/JoNil/elf2uf2-rs[elf2uf2-rs] for converting the generated elf binary into a uf2 file. diff --git a/docs/modules/ROOT/pages/project_structure.adoc b/docs/modules/ROOT/pages/project_structure.adoc new file mode 100644 index 00000000..31417d09 --- /dev/null +++ b/docs/modules/ROOT/pages/project_structure.adoc @@ -0,0 +1,80 @@ += Project Structure + +There are many ways to configure embassy and it's components for your exact application. The link:https://github.com/embassy-rs/embassy/tree/main/examples[examples] directory for each chipset demonstrate how your project structure should look. Let's break it down: + +The toplevel file structure of your project should look like this: +[source,plain] +---- +{} = Maybe + +my-project +|- .cargo +| |- config.toml +|- src +| |- main.rs +|- build.rs +|- Cargo.toml +|- {memory.x} +|- rust-toolchain.toml +---- + +=== .cargo/config.toml + +This directory/file describes what platform you're on, and configures link:https://github.com/probe-rs/probe-rs[probe-rs] to deploy to your device. + +Here is a minimal example: + +[source,toml] +---- +[target.thumbv6m-none-eabi] # <-change for your platform +runner = 'probe-rs run --chip STM32F031K6Tx' # <- change for your chip + +[build] +target = "thumbv6m-none-eabi" # <-change for your platform + +[env] +DEFMT_LOG = "trace" # <- can change to info, warn, or error +---- + +=== build.rs + +This is the build script for your project. It links defmt (what is defmt?) and the `memory.x` file if need be. This file is pretty specific for each chipset, just copy and paste from the corresponding link:https://github.com/embassy-rs/embassy/tree/main/examples[example]. + +=== Cargo.toml + +This is your manifest file, where you can configure all of the embassy components to use the features you need. + +TODO: someone should exhaustively describe every feature for every component! + +=== memory.x + +This file outlines the flash/ram usage of your program. It is especially useful when using link:https://github.com/embassy-rs/nrf-softdevice[nrf-softdevice] on an nRF5x. + +Here is an example for using S140 with an nRF52840: + +[source,x] +---- +MEMORY +{ + /* NOTE 1 K = 1 KiBi = 1024 bytes */ + /* These values correspond to the NRF52840 with Softdevices S140 7.0.1 */ + FLASH : ORIGIN = 0x00027000, LENGTH = 868K + RAM : ORIGIN = 0x20020000, LENGTH = 128K +} +---- + +=== rust-toolchain.toml + +This file configures the rust version and configuration to use. + +A minimal example: + +[source,toml] +---- +[toolchain] +channel = "nightly-2023-08-19" # <- as of writing, this is the exact rust version embassy uses +components = [ "rust-src", "rustfmt" ] # <- optionally add "llvm-tools-preview" for some extra features like "cargo size" +targets = [ + "thumbv6m-none-eabi" # <-change for your platform +] +----