Sungrow TCU project (QT)

This project is the TCU back and the front program for the IDC-30E european standard charger, whose project code is Normandie. The system diagram indicates as follows:

In the project, the process interaction with JAVA program remains as IPC_PIPE communication. Later in 180kW's project, it will be updated to UNIX domain socket.

IDE: QtCreator

Language: C++、QML

tag's name is compliant to semantic versioning. With the every release, the tag must be uploaded with the commit message and the release situation, for example in which run of the TR5, release date, in which products are they going to flash in, etc.

When adding tag, the command is as follows:

git tag -a v1.0.10 -m "release v1.0.8 for TR5 2nd round, release at 05/12/2023, front/back software change"

If you want to check the commit messages for the tag, input:

git tag -l -n9

In order to avoid the restrictions of the GNU General Public License(GPL), all the open source libraries with GPL used by this program are packaged in the form of DDL, as to limit the "infectiousness" of the GPL into the DDL, rather than the entire program. The back-end program invokes the DDL through the binary mode. Some configurations are required, the following uses the AESlib library as an example:

The build path is set to /TcuProgram/AESlib/build, and the tool chain is set to desktop or feiling (cross-compilation). Note that the tool chain needs to be selected according to the final program running platform.

Compile the DDL, and obtain 4 output files (.so files, etc.), At this point, copy the header file (.h file) of the AESlib to the AESlib's own compilation bulid folder (/TcuProgram/AESlib/build) without copying its implementation code (.c file). If you accidentally copy the header files to the build folder of the backend program, you must manually delete them. The clean function of qt cannot completely clean up this files, which will cause compilation failure.

The back-end program adds the compiled output path of the DDL (AESlib), as shown in the blue part of the figure, and then compiles.

Use export LD_LIBRARY_PATH=$LD_LIBRARY_PATH: to add the runtime path of the dynamic link library, and then start the background program. For the specific implementation, please refer to the startTCU.sh script file.

The semantic release automates tagging and hard-coded software version writing. The following documents explain how to set up and prepare the semantic release CI and the intention of the configurations.

The semantic release setup is highly depending on the team's workflow. The following screenshot explains the Sungrow Benelux's software development team's workflow.

The common workflow follows the software cycle. The branches and their functions are explained in the following.

The alpha users or the beta users can be different depending on the different situations. In some cases, beta pre-release might even be skipped especially during the TR4/TR5. For the on-site installed chargers, before conducting the OTA, the beta releasing stage is always mandatory.

The github workflow script is implemented in release.yml file. The followings are some key configurations.

on:
  push:
    branches:
      - G2/main # or main
      - "alpha/*"
      - "beta/*"
      - "release/*"

The triggering branches are listed based on the workflow. Only main, alpha, beta, release will trigger the automatic semantic release.

        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

The GITHUB_TOKEN is set in the repo's setting. NPM_TOKEN is set in the NPM account.

run: npx semantic-release

The command is the actual running semantic release step.

NPM should be configured first locally to enable the semantic release functions. The following steps are needed:

n lts # update the npm to the latest version
npm install --save-dev semantic-release # install semantic release
npm install --save-dev @semantic-release/exec # install the script execution of the semantic release during the CI
npm install --save-dev @semantic-release/git # install the assets commit tool during the CI
npm init # init the package.json dependencies, name, version, repo URL etc to prepare the semantic release

The scripts listed in the plugins field will be executed in order. Every plugin has its own execution steps:

[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "verifyConditions" from "@semantic-release/exec"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "verifyConditions" from "@semantic-release/npm"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "verifyConditions" from "@semantic-release/exec"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "verifyConditions" from "@semantic-release/github"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "verifyConditions" from "@semantic-release/git"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "analyzeCommits" from "@semantic-release/commit-analyzer"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "analyzeCommits" from "@semantic-release/exec"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "analyzeCommits" from "@semantic-release/exec"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "verifyRelease" from "@semantic-release/exec"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "verifyRelease" from "@semantic-release/exec"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "generateNotes" from "@semantic-release/exec"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "generateNotes" from "@semantic-release/exec"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "prepare" from "@semantic-release/exec"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "prepare" from "@semantic-release/npm"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "prepare" from "@semantic-release/exec"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "prepare" from "@semantic-release/git"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "publish" from "@semantic-release/exec"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "publish" from "@semantic-release/npm"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "publish" from "@semantic-release/exec"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "publish" from "@semantic-release/github"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "addChannel" from "@semantic-release/exec"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "addChannel" from "@semantic-release/npm"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "addChannel" from "@semantic-release/exec"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "addChannel" from "@semantic-release/github"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "success" from "@semantic-release/exec"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "success" from "@semantic-release/exec"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "success" from "@semantic-release/github"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "fail" from "@semantic-release/exec"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "fail" from "@semantic-release/exec"
[9:49:18 PM] [semantic-release] › ✔  Loaded plugin "fail" from "@semantic-release/github"

The semantic release will execute each step of the plugin and also each plugin according to the defined sequence in the package.json. If the further customizations of the semantic-release is needed, for example generating other assets or executing bash scripts in between, this execution order could be helpful.

The essential functions in the** package.json **are described as follows.

    "branches": [
      "G2/main",
      {
        "name": "beta/*",
        "prerelease": "${name.replace('beta/', '') || 'beta'}"
      },
      {
        "name": "alpha/*",
        "prerelease": "${name.replace('alpha/', '') || 'alpha'}"
      },
      {
        "name": "release/*",
        "prerelease": "${name.replace('release/', '')}"
      }
    ]

G2/main is configured as the normal version forwarding, every time a push to the G2/main is triggered, the version number will be increased based on the commit analyzer result. For example, if the current version is v1.1.0, a minor update is triggered at the G2/main, the semantic release will trigger a version increase from v1.1.0 to v1.2.0 and tagging.

Alpha, beta, releases branches are configured as the pre-release branches. The semantic release will automatically take the suffix and composite as a new tag. The followings are the example.

          "releaseRules": [
            {
              "type": "chore",
              "release": false
            },
            {
              "type": "docs",
              "release": false
            },
            {
              "type": "fix",
              "release": "patch"
            },
            {
              "type": "feat",
              "release": "minor"
            }
          ]

The commit analyzer will scan through the commit history and detect the keywords until the last tagging. The commit format in the repo follows the angular format, the commit history will apply the rules accordingly. For example, if any "feat" type exists since the last tagging, the next release version's** minor version** will increase. If only "fix" type exists, the patch version will be increased.

        "@semantic-release/exec",
        {
          "verifyReleaseCmd": "if [ -z \"$CI\" ];then echo \"running locally, skip env versioning check\"; else echo \"NEXT_RELEASE_VERSION=${nextRelease.version}\" >> $GITHUB_ENV;fi",
          "prepareCmd": "chmod +x ./replace_version.sh; ./replace_version.sh -i ${nextRelease.version}",
          "publishCmd": "echo \"publish version: ${nextRelease.version}\"",
          "successCmd": "echo \"Version: ${nextRelease.version}\" release success"
        }

The first exec plugin is added after the commit-analyzer. In between the semantic releasing, the version should be hard coded into the .qmake.conf file to support the MainProcess / chargingDemo's version hard coding.

The script in the verifyReleaseCmd will write the new release version into the execution environment, so that the other scripts can use it.

prepareCmd's script will execute the replace.version.sh script in the repo to:

1. Write the next release semantic style version into the .qmake.conf
2. Convert the semantic style version into the Sungrow style version, and write it into the .qmake.conf
3. Extract the suffix of the version, for example the alpha, beta or release suffix and write it into the .qmake.conf

      [
        "@semantic-release/exec",
        {
          "prepareCmd": "npm run changelog"
        }
      ],

This execution is executed after the npm module, based on the version written into the package.json, the changelog script will be executed to automatically generate a release note containing all the changes for each version.

The changelog configurations are as follows:

  "scripts": {
    "release": "release-it",
    "changelog": "conventional-changelog -p custom-config -i CHANGELOG.md -s -r 0"
  },
  "changelog": {
    "bugsUrl": "https://github.com/Sungrow-Benelux/TcuProgram/issues/",
    "emojis": true,
    "authorName": true,
    "authorEmail": true
  },

        "@semantic-release/git",
        {
          "assets": [
            "package.json",
            "package-lock.json",
            "CHANGELOG.md",
            "Back/.qmake.conf"
          ],
          "message": "chore(release): ${nextRelease.version} [skip ci]"
        }

Every time a semantic release is conducted, 4 files will be changed, the CI script will create an additional commit to upload them.