Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Build BSP is only optional, and not even required for the Simulation #17

Merged
merged 3 commits into from
Jan 6, 2025
Merged

Build BSP is only optional, and not even required for the Simulation #17

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
44b5bc3
Build BSP is only optional, and not even required for the Simulation
nhouze-microej Dec 20, 2024
984c1bf
apply suggestions and reorder the import/toolchain setup/runOnDevice/…
nhouze-microej Dec 20, 2024
1753535
Remove usage of 'please' word according to documentation rules
tdelhomenie-microej Jan 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
186 changes: 103 additions & 83 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,29 +72,114 @@ The <VEE_PORT> is derived into:
- SDK Dist. `<MICROEJ_SDK_VERSION>` or higher, available [here](https://developer.microej.com/microej-sdk-software-development-kit/)
- <BOARD_NAME> board

## BSP Setup
## <VEE_PORT> Setup

[Open the VEE Port project in your favorite IDE](https://docs.microej.com/en/latest/SDK6UserGuide/importProject.html)
by selecting the root folder of the cloned repository.

The project contains the following subprojects:

- `vee-port`: Contains the <VEE_PORT> configuration description.
Some modules are described in a specific sub-folder / with some optional configuration files
(`.properties` and / or `.xml`).

- `bsp`: Contains a ready-to-use BSP software project for the <BOARD_NAME> board, including a <CIDE> project,
an implementation of MicroEJ Core Engine (and extensions) port on <RTOS> and the <BOARD_NAME> board support package.

- `vee-port/extensions/front-panel`: Contains the board description and images for the Simulator.
This project is updated once the <VEE_PORT> is built.

- `vee-port/extensions/image-generator`: Contains the Image Generator extension.
This project is updated once the <VEE_PORT> is built.

- `vee-port/mock`: Contains a Mock.
This project is updated once the <VEE_PORT> is built.

- `app`: Contains a sample application which uses the <VEE_PORT>.

By default, the <VEE_PORT> is configured as a Mono-Sandbox Evaluation
<VEE_PORT> (Refer to the [RELEASE NOTES](./RELEASE_NOTES.md) limitations section for more details).

## Run an Application on the Simulator

To run an Application on the Simulator, the BSP or C/C++ Toolchain are not required.

- Run the `app` sample Application [on the Simulator](https://docs.microej.com/en/latest/SDK6UserGuide/runOnSimulator.html).
This automatically builds the <VEE_PORT> and uses it.

The build may take several minutes.
The first time, the <VEE_PORT> build requires to download modules that are available on the MicroEJ Central Repository.

Wait for the Application start, or for the final message:

```sh
BUILD SUCCESSFUL
```

An evaluation license is needed for building an Application. Refer to
https://docs.microej.com/en/latest/SDK6UserGuide/licenses.html#evaluation-licenses
for information on how to acquire and activate a license.

## Run an Application on the Device

To build and run the Application on the Device, the BSP and C/C++ Toolchain are required.

### Toolchain Setup

Install the <BOARD_MANUFACTURER> toolchain as described [here](<board_toolchain_setup_documentation_url>).

### Windows Toolchain
- Windows Toolchain
- C/C++ toolchain name: <C/C++ toolchain name>
- C/C++ toolchain version: <C/C++ toolchain version>
- C/C++ toolchain [download link](<windows_toolchain_download_url>)

- C/C++ toolchain name: <C/C++ toolchain name>
- C/C++ toolchain version: <C/C++ toolchain version>
- C/C++ toolchain [download link](<windows_toolchain_download_url>)
Refer to the <BOARD_MANUFACTURER> documentation available [here](<manufacturer_windows_toolchain_setup_documentation_url>)
for more details.

Please refer to the <BOARD_MANUFACTURER> documentation available [here](<manufacturer_windows_toolchain_setup_documentation_url>)
- Linux Toolchain
- C/C++ toolchain name: <C/C++ toolchain name>
- C/C++ toolchain version: <C/C++ toolchain version>
- C/C++ toolchain [download link](linux_toolchain_download_url>)

tdelhomenie-microej marked this conversation as resolved.
Show resolved Hide resolved
Refer to the <BOARD_MANUFACTURER> documentation available [here](<manufacturer_linux_toolchain_setup_documentation_url>)
for more details.

### Linux Toolchain
### BSP Setup

- C/C++ toolchain name: <C/C++ toolchain name>
- C/C++ toolchain version: <C/C++ toolchain version>
- C/C++ toolchain [download link](linux_toolchain_download_url>)
The build scripts expect the toolchain to be installed at a known
location. You can configure it, if you installed it elsewhere, by overriding
environment variables. The environment variables are declared in the
`set_project_env*` script. They can be defined globally by the user or
in the `set_local_env*` scripts. When the `build.bat` (`build.sh`)
scripts is executed, the `set_local_env.bat` (`set_local_env.sh`) script
is imported if it exists. Create and configure these files to
customize the environment locally. Template files are provided as
example, see `set_local_env.bat.tpl` and `set_local_env.sh.tpl`.

Please refer to the <BOARD_MANUFACTURER> documentation available [here](<manufacturer_linux_toolchain_setup_documentation_url>)
for more details.
_Note:_ Refer to the following public documentation link to get more details on this part:
- [VEE Port BSP Connection specification](https://docs.microej.com/en/latest/VEEPortingGuide/platformCreation.html#bsp-connection)
- [VEE Port Creation Training](https://docs.microej.com/en/latest/Trainings/tutorialCreatePlatformBuildAndRunScripts.html)

### Build and Run the Application

- Run the `app` sample Application [on Device](https://docs.microej.com/en/latest/SDK6UserGuide/runOnDevice.html).
This automatically builds the <VEE_PORT> and uses it.

The build may take several minutes.
The first time, the <VEE_PORT> build requires to download modules that are available on the MicroEJ Central Repository.
The <VEE_PORT> will also build the `bsp` project and link it with MicroEJ VEE and the Application to produce an executable.

### BSP Compilation
Wait for the Application start, or for the final message:

```sh
BUILD SUCCESSFUL
```

### BSP Manual Compilation

This section shows how to build the `bsp` project manually without having to rebuild the application.

Note: this can only be done if `buildExecutable` or `runOnDevice` have been called at least once, see [Run on Device](https://docs.microej.com/en/latest/SDK6UserGuide/runOnDevice.html)

To build the `bsp` project, open a
terminal and enter the following command lines:
Expand All @@ -113,29 +198,15 @@ $ cd "bsp/vee/scripts"
$ build.sh
```

The BSP project build is launched. Please wait for the final message:
The BSP project build is launched. Wait for the final message:

```sh
To flash all build output, run 'make flash' or:
```

The build script expects the toolchain to be installed at a known
location. You can configure it, if you installed it elsewhere, by overriding
environment variables. The environment variables are declared in the
`set_project_env*` script. They can be defined globally by the user or
in the `set_local_env*` scripts. When the `build.bat` (`build.sh`)
scripts is executed, the `set_local_env.bat` (`set_local_env.sh`) script
is imported if it exists. Create and configure these files to
customize the environment locally. Template files are provided as
example, see `set_local_env.bat.tpl` and `set_local_env.sh.tpl`.

_Note:_ Please refer to the following public documentation link to get more details on this part:
- [VEE Port BSP Connection specification](https://docs.microej.com/en/latest/VEEPortingGuide/platformCreation.html#bsp-connection)
- [VEE Port Creation Training](https://docs.microej.com/en/latest/Trainings/tutorialCreatePlatformBuildAndRunScripts.html)

## Board Setup

Please refer to the <BOARD_MANUFACTURER> documentation available [here](<board_setup_documentation_url>)
Refer to the <BOARD_MANUFACTURER> documentation available [here](<board_setup_documentation_url>)
for more details.

<Provide here image(s) of the board showing important things for the board setup (power supply connector, programming connector, logs output connector, jumpers configuration, etc.)>
Expand All @@ -144,7 +215,7 @@ for more details.

<The board can be powered by ...>

Please refer to the <BOARD_MANUFACTURER> documentation available [here](<board_power_supply_documentation_url>)
Refer to the <BOARD_MANUFACTURER> documentation available [here](<board_power_supply_documentation_url>)
for more details.

### Programming
Expand All @@ -170,7 +241,7 @@ $ cd "bsp/vee/scripts"
$ run.sh
```

The firmware is launched. Please wait for the final message:
The firmware is launched. Wait for the final message:

```sh
<Board flash final message>
Expand All @@ -194,7 +265,7 @@ for more details.
| Flow control | <Flow control value> |


Please refer to the <BOARD_MANUFACTURER> documentation available [here](<board_logs_setup_documentation_url>)
Refer to the <BOARD_MANUFACTURER> documentation available [here](<board_logs_setup_documentation_url>)
for more details.

### Firmware Debugging and Profiling
Expand All @@ -207,57 +278,6 @@ for more details.

<Firmware profiling analysis with SEGGER SystemView can be done using ...>

## <VEE_PORT> Setup

### <VEE_PORT> Import

[Open the VEE Port project in your favorite IDE](https://docs.microej.com/en/latest/SDK6UserGuide/importProject.html)
by selecting the root folder of the cloned repository.

The project contains the following subprojects:

- `vee-port`: Contains the <VEE_PORT> configuration description.
Some modules are described in a specific sub-folder / with some optional configuration files
(`.properties` and / or `.xml`).

- `bsp`: Contains a ready-to-use BSP software project for the <BOARD_NAME> board, including a <CIDE> project,
an implementation of MicroEJ Core Engine (and extensions) port on <RTOS> and the <BOARD_NAME> board support package.

- `vee-port/extensions/front-panel`: Contains the board description and images for the Simulator.
This project is updated once the <VEE_PORT> is built.

- `vee-port/extensions/image-generator`: Contains the Image Generator extension.
This project is updated once the <VEE_PORT> is built.

- `vee-port/mock`: Contains a Mock.
This project is updated once the <VEE_PORT> is built.

- `app`: Contains a sample application which uses the <VEE_PORT>.

By default, the <VEE_PORT> is configured as a Mono-Sandbox Evaluation
<VEE_PORT> (Please refer to the [RELEASE NOTES](./RELEASE_NOTES.md) limitations section for more details).

### <VEE_PORT> Build

To build the <VEE_PORT>:

- Run the `app` sample Application [on the Simulator](https://docs.microej.com/en/latest/SDK6UserGuide/runOnSimulator.html)
or [on Device](https://docs.microej.com/en/latest/SDK6UserGuide/runOnDevice.html).
This automatically builds the <VEE_PORT> and uses it.

The build may take several minutes.
The first time, the <VEE_PORT> build requires to download modules that are available on the MicroEJ Central Repository.

Please wait for the Application start, or for the final message:

```sh
BUILD SUCCESSFUL
```

An evaluation license is needed for building an Application. Please refer to
https://docs.microej.com/en/latest/SDK6UserGuide/licenses.html#evaluation-licenses
for information on how to acquire and activate a license.

## Testsuite Configuration

<To run a Testsuite on ...>
Expand Down