Skip to content

builder.md

Latest commit

 

History

History
261 lines (223 loc) · 10.8 KB

builder.md

File metadata and controls

261 lines (223 loc) · 10.8 KB
Raw

SDK Builder

Contents

Introduction

This SDK provides a powerful builder that tackles the firmware building and the configuration management of the SDK components and underlying dependent libraries and platforms such as micropython and esp-idf.

New Project Directory Organization

This is the recommended structure to start creating project based on this SDK.

<project-dir>/
    ├── sg-sdk           # a git submodule for the SDK
    ├── fw-builder.sh    # a new script to call the sg-sdk build-system
    ╰── app-dir          # project source directory
        ├── CMakeLists.txt    # main cmake file of the project
        │..                   # other project contents
        │..

This layout structure consists mainly of the following:

  • sg-sdk which is a git submodule to the SDK.
    git submodule add https://github.com/sg-wireless/sg-sdk.git

  • fw-builder.sh it is a simple script to call the underlying SDK build system and its contents should be like this:

      #!/bin/sh
  python3 sg-sdk/tools/builder/scripts/builder.py $*

  • app-dir a directory with a proper application name where the project contents will reside.
    The project source directory contents organization description can be found here

The user can construct different applications by the following layout structure:

<project-dir>/
    ├── sg-sdk           # a git submodule for the SDK
    ├── fw-builder.sh    # a new script to call the sg-sdk build-system
    ╰── projects         # applications directory
        ├── app-1-dir              # 1st application project
        │   ├── CMakeLists.txt     # main cmake file of the project
        │   │..                    # other project contents
        │   
        ├── app-2-dir              # 2nd application project
        │   ├── CMakeLists.txt     # main cmake file of the project
        │   │..                    # other project contents
        .   .
        .   .
        ├── app-N-dir              # Nth application project
        │   ├── CMakeLists.txt     # main cmake file of the project
        │   │..                    # other project contents

sg-sdk and fw-builder.sh are same as described before.

The projects directory contains as many directories as needed. Each directory carry a stand alone project(application) sources.

Build System Command Line Interface( CLI )

The build system offers a simple command line interface with colorful display. After you created your new project directory, you can type: fw-builder.sh --help to see the help of the build system which is similar to this screen shot:

Build System Help Screen

Then you will make your own build command that matches your project requirements

Examples of build commands:

Assume you have the F1 Starter Kit and you want to build a micropython app, then the build and flash commands will be:

# build command
./fw-builder.sh --board SGW3501-F1-StarterKit     \
                --project-dir <app-dir>
# flash command
./fw-builder.sh --board SGW3501-F1-StarterKit     \
                --project-dir <app-dir>           \
                flash --port <board-serial-port>

Assume you have the F1 SGW3201(F1-L) based custom board and you want to build a native C application, then the build and flash commands will be:

# build command
./fw-builder.sh --board SGW3201-F1L-OEM           \
                --variant native                  \
                --project-dir <app-dir>
# flash command
./fw-builder.sh --board SGW3201-F1L-OEM           \
                --variant native                  \
                --project-dir <app-dir>           \
                flash --port <board-serial-port>

F1 Output Image (Binaries)

All build outputs are compressed in a .tar.gz file with a name syntax: <board>-<fw-version>.tar.gz and contain the following files:

<board>-<fw-version>.tar.gz
    ├── bootloader.bin          # the bootloader binary
    ├── partition-table.bin     # the partition table binary
    ├── application.bin         # the main Firmware application binary
    ├── ota_data_initial.bin    # the OTA initial data partition binary
    ╰── flash_args              # the suitable esptool flashing arguments
                                # to be used by the flasher tool

The build outputs are placed under the following path based on the build command variables: sg-sdk/build/<app-dir-name>/F1/<board>/<variant>/<file>.tar.gz

and this is a hierarchy example showing the shape of the build tree with the build outputs.

<project-dir>/
    ├── sg-sdk           # a git submodule for the SDK
    │   ╰── build
    │       ├── app-1-dir
    │       │   ├── F1
    │       │   │   ├── SGW3101-F1W-OEM
    │       │   │   │   ├── micropython
    │       │   │   │   │   ├── SGW3131-F1-WS-OEM-v0.0.0.tar.gz
    │       │   │   │   ├── native
    │       │   │   │   │   ├── SGW3131-F1-WS-OEM-v0.0.0.tar.gz
    │       │   │   │   
    │       │   │   ├── SGW3201-F1L-OEM
    │       │   │   │   ├── micropython
    │       │   │   │   │   ├── SGW3201-F1L-OEM-v0.0.0.tar.gz
    │       │   │   │   ├── native
    │       │   │   │   │   ├── SGW3201-F1L-OEM-v0.0.0.tar.gz
    │       .   .   .   .   .
    │       # and so on and so forth for all apps/boards/variants
    │       .   .   .   .   .
    │       ├── app-2-dir
    │       │   ├── F1
    │       │   │   ├── SGW3101-F1W-OEM
    │       │   │   │   ├── micropython
    │       │   │   │   │   ├── SGW3131-F1-WS-OEM-v0.0.0.tar.gz
    │       │   │   │   ├── native
    │       │   │   │   │   ├── SGW3131-F1-WS-OEM-v0.0.0.tar.gz
    │       │   │   │   
    │       │   │   ├── SGW3201-F1L-OEM
    │       │   │   │   ├── micropython
    │       │   │   │   │   ├── SGW3201-F1L-OEM-v0.0.0.tar.gz
    │       │   │   │   ├── native
    │       │   │   │   │   ├── SGW3201-F1L-OEM-v0.0.0.tar.gz
    │       .   .   .   .   .
    │       # and so on and so forth for all apps/boards/variants
    │       .   .   .   .   .
    │       ╰── app-N-dir
    │           ╰── F1
    │               ├── SGW3101-F1W-OEM
    │               │   ├── micropython
    │               │   │   ├── SGW3131-F1-WS-OEM-v0.0.0.tar.gz
    │               │   ├── native
    │               │   │   ├── SGW3131-F1-WS-OEM-v0.0.0.tar.gz
    │               │   
    │               ├── SGW3201-F1L-OEM
    │               │   ├── micropython
    │               │   │   ├── SGW3201-F1L-OEM-v0.0.0.tar.gz
    │               │   ├── native
    │               │   │   ├── SGW3201-F1L-OEM-v0.0.0.tar.gz
    │               .   .   .
    │   
    │   
    │   
    ├── fw-builder.sh    # a new script to call the sg-sdk build-system
    ╰── projects         # applications directory
        ├── app-1-dir                 # 1st application project
        │   ├── CMakeLists.txt     # main cmake file of the project
        │   │..                    # other project contents
        │   
        ├── app-2-dir                 # 2nd application project
        │   ├── CMakeLists.txt     # main cmake file of the project
        │   │..                    # other project contents
        .   .
        .   .
        ├── app-N-dir                 # Nth application project
        │   ├── CMakeLists.txt     # main cmake file of the project
        │   │ .                    # other project contents