Skip to content

Commit b5ba624

Browse files
gonzolivelygonzolively
committed
Added board support guide and made minor changes to the index
1 parent 6b29143 commit b5ba624

7 files changed

Lines changed: 293 additions & 12 deletions

File tree

‎docs/board-support/adding-support/config.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: "Create a Device Config File"
3+
layout: default
4+
parent: Adding Board Support
5+
nav_order: 1
6+
---
7+
8+
# Create a Device Config File
9+
10+
The Ocre runtime requires specific configuration of your board's software features and hardware capabilities using Zephyr's Kconfig system. This guide will walk you through creating a device configuration file.
11+
12+
---
13+
14+
## What is a Device Config File?
15+
16+
In Zephyr, each board has default configurations defined in its defconfig file (`board_name_defconfig`). A device config file allows you to extend or override these default configurations without modifying the original files. While similar in purpose to Zephyr's standard Kconfig files, Ocre uses the `.conf` extension for board-specific configurations placed in the boards directory.
17+
18+
Config files are essential for:
19+
- Enabling required hardware drivers and peripherals
20+
- Setting memory and resource allocations
21+
- Configuring networking and communication interfaces
22+
- Enabling board-specific features needed by Ocre
23+
24+
---
25+
26+
## Creating Your Config File
27+
Creating a device config file often goes hand-in-hand with developing your overlay file, as build errors will indicate missing configuration options needed for your board's hardware and features. The specific configurations needed will vary based on your board's capabilities and requirements.
28+
29+
### Prerequisites
30+
Before creating your overlay file:
31+
- Check out Zephyr's [Kconfig System](https://docs.zephyrproject.org/latest/develop/application/index.html#kconfig-configuration)
32+
- Locate your boards (Zephyr) **name**, as found in the Zephyr [Supported Boards](https://docs.zephyrproject.org/3.7.0/boards/index.html) guide. (e.g. `nucleo_h563zi`)
33+
- Review your board's default config in the Zephyr source (`zephyr/boards/manufacturer/board_name/board_name_defconfig`)
34+
- Review board's technical documentation
35+
36+
{: .highlight}
37+
While the `board_name_defconfig` file provides a useful reference for understanding your board's default configurations, it may not include all the board's features or capabilities. Zephyr board support is an ongoing effort and may lag behind the latest hardware revisions or available peripherals. Use the defconfig file as a starting point, but verify and supplement its configurations with your board's datasheet and hardware documentation as needed.
38+
39+
40+
### Example Config
41+
Here's a sample config for STMicroelectronics `B-U585I-IOT02A` board:
42+
43+
```
44+
# ENC28J60 Ethernet driver
45+
CONFIG_GPIO=y
46+
CONFIG_SPI=y
47+
CONFIG_ETH_ENC28J60=y
48+
CONFIG_NET_L2_ETHERNET=y
49+
```
50+
51+
This example shows configuration options needed for the *enc28j60* ethernet controller that we specified in the overlay for the `B-U585I-IOT02A` board in the previous page (See the [overlay example](../overlay#example-overlay-file)).
52+
53+
### Steps
54+
55+
1. Create a blank file named `board_name.conf` (replacing `board_name` with your boards name) in the *top-level* `boards` directory (`application/boards`) in the Ocre Runtime project.
56+
2. Add required configurations:
57+
- Enable necessary drivers and peripherals
58+
- Configure hardware features defined in your overlay
59+
- Set any board-specific options
60+
3. Save your config file.
61+
4. Attempt to build the Ocre Runtime following the [**Building and Flashing the Ocre Runtime to Your Board**](../ocre-runtime) guide.
62+
5. As mentioned in the [**Create a Device Overlay File**](../overlay) page, most likely you will encounter errors, address them and try to build again.
63+
64+
{: .note}
65+
Reference Zephyr's [Kconfig Search](https://docs.zephyrproject.org/latest/kconfig.html#kconfig-search) for available configuration options and their descriptions.
66+
67+
---
68+
69+
## Next Steps
70+
If your board builds successfully, congratulations! You have successfully added board support for your device. Continue to the [**Contributing Board Support**](../contributing) page to learn how to get your board added to the official Ocre repos.

‎docs/board-support/adding-support/contributing.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: "Contributing Board Support"
3+
layout: default
4+
parent: Adding Board Support
5+
nav_order: 3
6+
---
7+
8+
# Contributing Board Support
9+
10+
Now that you've successfully added support for your board, the next step is contributing your work to the community!
11+
12+
---
13+
14+
## What to Contribute
15+
16+
To add official support for your board, you will need:
17+
- Your board's overlay file
18+
- Your board's configuration file
19+
- Any additional documentation about board-specific requirements, such as:
20+
- Required hardware (modules, shields, adapters, etc.)
21+
- Wiring or connection diagrams
22+
- Special setup instructions
23+
- Hardware revisions supported
24+
- (Optional) Update the [`ocre.code-workspace`](https://github.com/project-ocre/ocre-runtime/blob/main/ocre.code-workspace) file by adding your board name to the `board` input options in the "West Build" task.
25+
26+
---
27+
28+
## How to Contribute
29+
30+
Please follow our [Contributing Guidelines](https://github.com/project-ocre/ocre-runtime/blob/main/CONTRIBUTING.md) for detailed instructions on the contribution process, including how to submit your board support files via a Pull Request.

‎docs/board-support/adding-support/index.md‎

Lines changed: 19 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,27 @@ title: "Adding Board Support"
33
layout: default
44
parent: Board Support
55
nav_order: 0
6+
has_toc: false
67
---
78

89
# Adding Board Support
9-
This guide outlines the process of adding support for new development boards to the Ocre runtime. While we aim to support a wide range of boards, the embedded ecosystem is vast, and you may need to add support for your specific hardware.
1010

11-
Adding support for a new board involves:
12-
- Creating board-specific configurations
13-
- Testing and validating Ocre runtime functionality
14-
- Contributing your changes back to the project
11+
While we strive to support as many boards as possible in the Ocre project, the rapid pace of hardware innovation makes it impossible to maintain support for every device. This is where our community plays a crucial role in expanding the Ocre ecosystem by contributing board support for their specific hardware.
1512

16-
Follow the steps below to begin adding support for your development board.
13+
This guide will walk you through the process of creating the necessary configurations that allow Ocre to understand and interact with your board's devices, peripherals, and unique capabilities.
14+
15+
---
16+
17+
**Before proceeding with adding board support, ensure:**
18+
* Your board
19+
* Is [supported](https://docs.zephyrproject.org/3.7.0/boards/index.html) by Zephyr (v3.7.0)
20+
* Has a *minimum* of 550kb device memory
21+
* Has networking capabilities (either onboard or via external module)
22+
* You can build the Ocre Runtime [Using a Simulated Device](../../quickstart/firmware/simulated). We will use this as our development environment and it will help us validate that your project is properly set up before adding support for physical hardware.
23+
* You have a basic understanding of your board's hardware specifications and have access to your board's technical documentation
24+
25+
---
26+
27+
## Next Steps
28+
29+
Now that you have confirmed your development environment is working correctly and the Ocre Runtime can be ran with the native simulator, you're ready to begin adding support for your board. Continue to the [Create a Device Overlay](overlay) page to learn how to define your board's hardware configuration for the Ocre runtime.

‎docs/board-support/adding-support/ocre-runtime.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
title: "Building and Flashing Ocre to Your Board"
3+
layout: default
4+
parent: Adding Board Support
5+
nav_order: 2
6+
---
7+
8+
# Building and Flashing Ocre to Your Board
9+
10+
Now that you've created your board's overlay and configuration files, you're ready to build and flash the Ocre Runtime. This page provides the commands and steps needed to get Ocre running on your device. You'll likely reference this page frequently while iterating through your overlay and config file development.
11+
12+
---
13+
14+
15+
## Prerequisites
16+
Before attempting to build and flash the Ocre Runtime to your device ensure the following conditions are met:
17+
- Your *overlay* and *config* files have been created and placed in the top-level boards directory (`application/boards`).
18+
- Your board is connected via USB to your computer and connected via your console program.
19+
20+
---
21+
22+
## Building the Ocre Runtime
23+
24+
The build process will automatically incorporate your board's overlay and config files from the boards directory. If any configuration issues exist, the build will fail with helpful error messages indicating what needs to be fixed.
25+
26+
To **build** the Ocre Runtime:
27+
28+
1. Ensure you're in the projects root directory
29+
2. Run the following command, specifying your `board_name` as the target:
30+
31+
```sh
32+
west build -b board_name ./application -d build -- -DMODULE_EXT_ROOT=pwd/application
33+
```
34+
35+
{: .note}
36+
Find your exact board name in the Zephyr (v3.7.0) [Supported Boards Guide](https://docs.zephyrproject.org/3.7.0/boards/index.html).
37+
38+
---
39+
40+
## Flashing the Ocre Runtime
41+
Once built successfully, you can flash the Ocre Runtime to your device.
42+
43+
1. To **flash** the Ocre Runtime to your device, simply run:
44+
45+
```sh
46+
west flash
47+
```
48+
49+
If successful, you should see the following output in your console.
50+
51+
![](../success.png)
52+
53+
---
54+
55+
## Next Steps
56+
Once you've successfully built and flashed the Ocre Runtime to your board, continue to the [**Contributing Board Support**](../contributing) page to learn how to contribute your board configuration to the Ocre Runtime repo.

‎docs/board-support/adding-support/overlay.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
title: "Create a Device Overlay File"
3+
layout: default
4+
parent: Adding Board Support
5+
nav_order: 0
6+
---
7+
8+
# Create a Device Overlay File
9+
10+
The Ocre runtime, built on the Zephyr RTOS, requires proper configuration of your board's components and memory layout. This guide will walk you through creating a device overlay file.
11+
12+
---
13+
14+
## What is a Device Overlay File?
15+
16+
In Zephyr, each board has a default [Device Tree Source](https://docs.zephyrproject.org/latest/build/dts/intro-scope-purpose.html) (`.dts`) file that defines its hardware configuration, including memory mappings, peripherals, and bus configurations. An *overlay* file (`.overlay`)allows you to extend or modify this default configuration without changing the original source files.
17+
18+
For Ocre, proper overlay configuration is crucial for:
19+
- Defining flash memory partitions for the boot-loader and containers
20+
- Configuring board-specific hardware features
21+
- Ensuring correct memory allocation for the runtime
22+
23+
---
24+
25+
## Creating Your Overlay File
26+
Creating a device overlay file involves configuring your board's flash memory partitions, hardware peripherals, and possibly the filesystem for the Ocre Runtime to function properly. You'll need to understand your board's memory layout and hardware capabilities, as well as any additional modules you might need for networking support. Below you'll find requirements, examples, and step-by-step instructions to create your overlay.
27+
28+
### Prerequisites
29+
Before creating your overlay file:
30+
31+
- Check out Zephyrs [Introduction to Devicetree](https://docs.zephyrproject.org/latest/build/dts/intro.html) guide.
32+
- Locate your boards (Zephyr) **name**, as found in the Zephyr [Supported Boards](https://docs.zephyrproject.org/3.7.0/boards/index.html) guide. (e.g. `nucleo_h563zi`)
33+
- Review your boards `.dts` file as found in the Zephyr source (`zephyr/boards/manufacturer/board_name/board_name.dts`).
34+
- Review your board's technical documentation
35+
36+
{: .highlight}
37+
The `board_name.dts` file provides a foundational reference for your board's hardware configuration but may not describe all available peripherals, hardware features, or supported options. Zephyr's Device Tree support is an evolving process and may not fully align with your board's latest specifications or capabilities. Use the `.dts` file as a baseline, but cross-reference with your board's datasheet and hardware documentation to ensure accuracy and completeness in your overlay file.
38+
39+
40+
### Partition Layout Requirements
41+
Ocre uses MCUBoot as a boot-loader, therefore it requires setting up the flash partitions accordingly. (See the [MCUboot docs](https://docs.mcuboot.com/readme-zephyr.html) for full details.)
42+
43+
| Partition | Size (min) | Description |
44+
|----------|----------|----------|
45+
| `boot_partition` | 32k | MCUboot boot-loader |
46+
| `slot0_partition` | 256k | Primary slot for image 0 |
47+
| `slot1_partition` | 256k | Secondary slot for image 0 |
48+
| `storage_partition` | 8k | Storage for custom Zephyr functions |
49+
| `user_data` | Remaining memory | Storage for Ocre container definitions and images |
50+
51+
{: .note}
52+
Not all boards will require you to define *all* the above partitions in the `.overlay` file, as their `.dts` file may already define them. Please refer to your boards `.dts` file beforehand and only define (or modify) partitions if they're needed.
53+
54+
### Additional Device Tree Configurations
55+
56+
Beyond flash partitions, your board may require additional device tree configurations depending on its hardware and requirements.
57+
58+
Common configurations include:
59+
60+
- **File System Support**: Configure file system tables via `fstab` nodes for container storage
61+
- **Chosen Nodes**: Specify system-wide defaults like console, shell, and flash devices
62+
- **Hardware Peripherals**: Enable and configure communication interfaces like:
63+
- Ethernet modules (like the *enc28j60* example below)
64+
- WiFi modules (such as esp32 or other wireless adapters)
65+
- Serial interfaces and other board-specific peripherals
66+
67+
{: .note}
68+
These configurations vary by board. If your board lacks built-in networking capabilities, you'll need to add support for an external ethernet or WiFi module as Ocre requires internet connectivity for container management.
69+
70+
### Example Overlay File
71+
Here's a sample overlay for STMicroelectronics `B-U585I-IOT02A` board:
72+
73+
```
74+
&spi1 {
75+
enc28j60: ethernet@0 {
76+
status = "okay";
77+
reg = <0>;
78+
compatible = "microchip,enc28j60";
79+
int-gpios = <&gpioc 1 GPIO_ACTIVE_LOW>;
80+
spi-max-frequency = <10000000>;
81+
local-mac-address = [ 00 80 00 01 02 03 ];
82+
full-duplex;
83+
};
84+
};
85+
86+
&flash0 {
87+
partitions {
88+
user_data_partition: partition@100000 {
89+
label = "user_data";
90+
reg = <0x00100000 DT_SIZE_K(256)>;
91+
};
92+
};
93+
};
94+
```
95+
96+
As mentioned in the previous section, many boards already have some partitions defined in their `.dts` file. This board only needed an additional `user_data_partition` definition in its overlay as the other required partitions were defined in its base [DTS file](https://github.com/zephyrproject-rtos/zephyr/blob/main/boards/st/b_u585i_iot02a/b_u585i_iot02a.dts).
97+
98+
You also may have noticed that this board also has an added configuration for the *enc28j60* ethernet controller as that board does not have an onboard ethernet or Wifi device.
99+
100+
### Steps
101+
102+
Creating an overlay file will most likely take a bit of iteration as each board and requirements are unique. Also, depending on which options, devices, and peripheral you place in the overlay you may require additional configuration options to get your build to work so please see [**Creating a Device Config**](../config) to do that.
103+
104+
1. Create a blank file named `board_name.overlay` (replacing `board_name` with your boards name) in the *top-level* `boards` directory (`application/boards`).
105+
2. Add the required partition layout to your overlay file, while referencing the [**Partition Layout Requirements**](#partition-layout-requirements) section and [**Example Overlay File**](#example-overlay-file) example above.
106+
3. Save your overlay file.
107+
4. Attempt to build the Ocre runtime following the [**Building and Flashing Ocre to Your Board**](../ocre-runtime) guide.
108+
5. Most likely you will encounter errors, address them in the overlay (or in the [**config**](../config)) and try to build again.
109+
110+
---
111+
112+
## Next Steps
113+
If your board builds successfully, congratulations! Continue to the [**Contributing Board Support**](../contributing) page to figure out how to get your board added to the official Ocre repos.
114+
115+
If you weren't successful by simply creating an overlay, then see the [**Create a Device Config**](../config) to add necessary configuration options for your board.

‎docs/board-support/adding-support/success.png‎

117 KB
Loading

‎docs/board-support/index.md‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22
title: Board Support
33
layout: default
44
has_children: true
5-
nav_order: 6
5+
nav_order: 6
6+
has_toc: false
67
---
78
# Board Support
89
The Ocre runtime supports various development boards, each offering different features and capabilities.
@@ -17,11 +18,7 @@ The Ocre runtime supports various development boards, each offering different fe
1718
---
1819

1920
## Using this Documentation
20-
1. First, select your board's manufacturer in the **sidebar** to review required tools and setup instructions specific to that manufacturer's development boards
21-
2. After installing the necessary tools, find your specific board's documentation for detailed hardware setup and flashing instructions
22-
23-
{: .important}
24-
Make sure to review and install all required tools outlined in the manufacturer's page before proceeding to your specific board's instructions.
21+
Select your board's manufacturer in the **sidebar** to review required tools and setup instructions specific to that manufacturer's development boards
2522

2623
---
2724

0 commit comments

Comments
 (0)