Optional Docker and spkg

Optional Docker and spkg#

The UNIT CH55x SDK includes optional Docker-based tooling through spkg for Makefile-based examples. Use PlatformIO first for new projects; Docker is kept as a secondary workflow for isolated builds and legacy examples.

Use this page only when a project specifically needs the Docker/spkg workflow.

Note

This is the only chapter that documents spkg usage. For new project implementation, use PlatformIO Support for CH55x.

Requirements#

Common Requirements#

Linux#

  • Python 3.

  • Permission to run Docker.

  • Superuser privileges may be required during Docker installation or when the current user is not part of the docker group.

Windows#

Installation#

Clone the SDK repository:

git clone https://github.com/UNIT-Electronics-MX/unit_ch55x_sdk.git
cd unit_ch55x_sdk

On Linux, make the launcher executable:

chmod +x spkg/spkg

Optional global installation on Linux:

cd spkg
sudo ln -s "$(pwd)/spkg" /usr/local/bin/spkg

On Windows, run the launcher from Git Bash:

./spkg/spkg.bat --help

Build the Docker Image#

Start Docker Desktop or the Docker daemon before running the SDK commands.

./spkg/spkg compose

If spkg was installed globally:

spkg compose

Compile a Project#

./spkg/spkg -p ./examples/Blink

With global installation:

spkg -p ./examples/Blink

Run Make Targets#

The command after the project path is forwarded to make inside the container. Common targets are clean, all, and hex.

./spkg/spkg -p ./examples/Blink clean
./spkg/spkg -p ./examples/Blink all
./spkg/spkg -p ./examples/Blink hex

Create a New Project#

The init command creates a new project directory.

./spkg/spkg init examples/project

Output#

For Makefile-based projects, the compiled binary is generated at:

examples/Blink/build/main.bin

Other generated files, such as HEX output, are written under the same project build/ directory according to the project Makefile.

Flash Tools#

Generated firmware can be flashed with one of the supported CH55x tools:

Configure Docker Without sudo on Linux#

Docker commands may require sudo until the current user is added to the docker group.

Install Docker Engine#

Select one installation method.

sudo apt update
sudo apt install -y docker.io

Verify Docker Operation#

sudo systemctl start docker
sudo systemctl enable docker
docker version

Add the User to the docker Group#

sudo usermod -aG docker $USER
newgrp docker

Log out and back in if the group change is not applied in the current shell.

Validate Non-Privileged Docker Usage#

Run Docker without sudo:

docker ps

The command should return either an empty container list or the column headers.

Verify Docker Compose#

Check the modern Docker Compose plugin first:

docker compose version

Some systems also provide the classic command:

docker-compose version

If Docker Compose is missing, install the package for your distribution. On Ubuntu-based systems:

sudo apt install docker-compose-plugin

Optional Socket Permission Check#

Inspect the Docker socket:

ls -l /var/run/docker.sock

Expected group ownership:

srw-rw---- 1 root docker ...

If the group or permissions are wrong:

sudo chown root:docker /var/run/docker.sock
sudo chmod 660 /var/run/docker.sock

Troubleshooting#

  • If spkg compose fails, confirm Docker is running with docker ps.

  • If Linux requires sudo for every Docker command, re-check the docker group membership and start a new login session.

  • If Windows cannot run spkg, use Git Bash and call ./spkg/spkg.bat.

  • If a build cannot find a Makefile target, verify that the path passed with -p points to the project directory that contains the Makefile.

Contents