# Target setup for Software Renderer 2D

This is a target setup guide for Software Renderer 2D Platform. it includes guides for all Targets of the Software Renderer 2D Platform

# Target setup guide for the ESP32S3 (ESP32S3-Touch-LCD-2.8C)

#### <span lang="en-us">Before you Begin</span>

<span lang="en-us">Before starting with the setup guide, we recommend the following to get familiar with CGI-Studio:</span>

- <span lang="en-us">Explore CGI-Studio  
    Read the <span style="color:rgb(230,126,35);">[Quick Start Guide](https://doc316en.candera.eu/books/getting-started/chapter/quick-start-guide)</span>.   
    </span>
- <span lang="en-us">Learn to create SceneComposer Solutions  
    The documentation provides instructions on how to create simple SceneComposer solutions. To access SceneComposer navigate to:  
    *&lt;cgi-studio-installation-path&gt;\\bin\\SceneComposer\\SceneComposer.exe*</span>
- <span lang="en-us">Generate Assets for Simulation and Target Environments  
    You can find guidance on generating assets from solutions (binary files containing solution information for the player) for both simulation and target environments in the <span style="color:rgb(230,126,35);">[documentation](https://doc316en.candera.eu/books/asset-library-generation)</span>.  
    </span>

<span lang="en-us">With this knowledge you should be fit to complete this guide.</span>

#### <span lang="en-us">Setup</span>

##### <span lang="en-us">Template Scenes</span>

<span lang="en-us">When using a template scene as the base for development, the surfaceFormat inside the RenderTarget needs to be set to SurfaceFormatRGB565.</span>

##### <span lang="en-us">IDE</span>

<span lang="en-us">To compile a CourierSampleApp Example for the target ESP IDF needs to be installed within Visual Studio Code: <span style="color:rgb(230,126,35);">[Getting Started with VS Code IDE - ESP32 - — ESP-IDF Programming Guide v4.3.1 documentation](https://docs.espressif.com/projects/esp-idf/en/v4.3.1/esp32/get-started/vscode-setup.html)</span></span>

##### <span lang="en-us">Device Connection to host PC</span>

<span lang="en-us">The ESP32S3-Touch-LCD-2.8C target from waveshare has two USB-C ports. For flashing connect the one labled "UART" to the host PC.</span>

##### <span lang="en-us">Compile and flash</span>

<span lang="en-us">Inside *cgi\_studio\_apps\\References\\ESP-IDF* a example project can be found. Open this project within Visual Studio code </span>

<span lang="en-us">It might be necessary to adjust the selected COM port. For this click the *COM&lt;current port number&gt;* on the bottom task bar and select one of the available com ports:</span>

<div drawio-diagram="8848"><img src="https://doc316en.candera.eu/uploads/images/drawio/2025-12/drawing-7-1765434647.png" alt="drawing-7-1765434647.png"/></div>

<span lang="en-us">To compile and flash the target press the *ESP-IDF: Build, Flash and Monitor* on the bottom Task bar. </span>

<div drawio-diagram="8849"><img src="https://doc316en.candera.eu/uploads/images/drawio/2025-12/drawing-7-1765434675.png" alt="drawing-7-1765434675.png"/></div>

<span lang="en-us">After compilation and flashing an example project can be seen on the display of the ESP32S3.</span>

#### <span lang="en-us">Replacing the Asset File</span>

<span lang="en-us">The current setup requires the Asset binary file to be converted to a C Array that can be placed directly within the code. For converting the binaries bin2c from segger can be used:</span>

<div drawio-diagram="8850"><img src="https://doc316en.candera.eu/uploads/images/drawio/2025-12/drawing-7-1765434771.png" alt="drawing-7-1765434771.png"/></div>

<span lang="en-us">This program generates a file with a C array inside. This array needs to be copied into the following file: *cgi\_studio\_courier\_apps\\src\\CourierSampleAppLight\\AppPlatform\\Target\_FreeRTOS\_XTENSA\\Solution.c*</span>

<span lang="en-us">The array needs to look like the following: </span>*const unsigned char \_ac2D\_Basic*. Inside the AppEnvironment.cpp file of the same directory this array is referenced:

extern const unsigned char \_ac2D\_Basic\[1130352UL + 1\];  
\#define ASSET\_START \_ac2D\_Basic

When updating the Solution.c make sure that the size of the array is the same inside Solution.c and in AppEnvironment.cpp

After the array has been replaced the project can be recompiled and flashed like described in the previous step.

# Target Setup for the STM32MP135f and other Linux based targets

This guide aims to explain how to setup a Linux based target for the Software Renderer Platform and how to build a player for this target. The guide was tested on the STM32MP135f but the setup should be similar on most other Linux platforms that support DRM/KMS.

### <span lang="en-us">Before you begin</span>

<span lang="en-us">Before starting with the setup guide, we recommend the following to get familiar with CGI-Studio:</span>

- <span lang="en-us">Explore CGI-Studio  
    Read the <span style="color:rgb(230,126,35);">[Quick Start Guide](https://doc316en.candera.eu/books/getting-started/chapter/quick-start-guide)</span>.   
    </span>
- <span lang="en-us">Learn to create SceneComposer Solutions  
    The documentation provides instructions on how to create simple SceneComposer solutions. To access SceneComposer navigate to:  
    *&lt;cgi-studio-installation-path&gt;\\bin\\SceneComposer\\SceneComposer.exe*</span>
- <span lang="en-us">Generate Assets for Simulation and Target Environments  
    You can find guidance on generating assets from solutions (binary files containing solution information for the player) for both simulation and target environments in the <span style="color:rgb(230,126,35);">[documentation](https://doc316en.candera.eu/books/asset-library-generation)</span>.  
    </span>

<span lang="en-us">With this knowledge you should be fit to complete this guide.</span>

#### <span lang="en-us">Target and build setup</span>

<span lang="en-us">For setup of the ST32MP135f-DK follow the guide provided by STM: <span style="color:rgb(230,126,35);">[Populate the target and boot the image - stm32mpu](https://wiki.st.com/stm32mpu/wiki/Getting_started/STM32MP1_boards/STM32MP135x-DK/Let%27s_start/Populate_the_target_and_boot_the_image)</span></span>

<span lang="en-us">For setup of the SDK (inside a WSL or Linux host PC) to build a player for the STM32 follow this guide provided by STM: <span style="color:rgb(230,126,35);">[Install the SDK - stm32mpu](https://wiki.st.com/stm32mpu/wiki/Getting_started/STM32MP1_boards/STM32MP135x-DK/Develop_on_Arm%C2%AE_Cortex%C2%AE-A7/Install_the_SDK)</span></span>

#### <span lang="en-us">Building the Player</span>

<span lang="en-us">tested inside an Ubuntu WSL:</span>

1. <span lang="en-us">source the SDK like described in the Install the SDK Guide from STM</span>
2. <span lang="en-us"> within the root directory of cgi trunk:</span>
    1. <span lang="en-us">mkdir build &amp;&amp; cd build</span>
    2. <span lang="en-us"><span>cmake -DCMAKE\_TOOLCHAIN\_FILE="../cgi\_studio\_devices/src/SoftwareRenderer2D/ToolchainFiles/GCC-toolchain-STM32MP135f-DrmKms-Linux.txt" -DCGIDEVICE\_EVDEV\_INPUT\_ENABLED=ON ../cmake/Candera/Player/ &amp;&amp; make -j</span></span>

<span lang="en-us"><span>The Player should now be built and can be uploaded to the Target.</span></span>

#### Uploading Player and Asset file to the target

1. Connect an USB-C Cable to CN7 USB-C of the target to the host pc
2. Connect USB-C Power cable to the PWR USB-C port
3. After the device boots a ssh connection can be established to the device: 
    1. ssh [root@192.168.7.162](mailto:root@192.168.7.162) #the static ip address of the target
    2. It might be necessary to kill weston if it is still running. It NEEDS to be killed otherwise there will be a conflict with the Player over display access
4. Copy the compiled player and in Scene Composer generated Asset.bin file to the target (using WinScp or scp) and run them like so: 
    1. ./Player Asset.bin