Brewblox firmware
This is the main firmware source code repository for the Brewblox Spark. For user documentation and install guides, see https://www.brewblox.com.
Development
The development environment is based on the development container feature in the Visual Studio Code editor. A Dockerfile is provided that includes the required dependencies for most build types.
When opening the repository in VSCode, you will be prompted to reload the editor in the container. On first load, it will download the Docker image. This can take a while, as it's a big image.
When this is done, intellisense, build tasks, and the VSCode terminal will run in the container.
If you wish to use a different editor, you will need to either manually build the Docker image, or reproduce the installation steps on your local machine.
Development: Submodules
The repository includes multiple nested Git submodules. These are not loaded by default when you clone the repository. To load them, run:
git submodule update --init --recursive --depth 1 --single-branch
Development: signing key
If the local ESP build fails with an error that secure_boot_signing_key.pem could not be located, create this file by copying the placeholder key.
cd app/brewblox-esp
cp PLACEHOLDER_SIGNING_KEY.pem ./secure_boot_signing_key.pemDevelopment: trusted directories
The nested ESP submodules have a different owner (root) when installed in the devcontainer. To resolve this, run the following commands on the host, and then restart the container:
git config --global --add safe.directory /opt/esp/idf
git config --global --add safe.directory /opt/esp/idf/components/openthread/openthreadProtobuf
Communication with the Spark service is encoded using Protocol Buffers (protobuf).
The message definitions are stored in the brewblox-proto repository, which is included as a submodule. The messages are compiled to C/C++, and the generated files are committed in this repository. A build-time check is done whether the compiled files match the active brewblox-proto submodule commit.
To assist with tests, messages are compiled twice: once using Nanopb for the actual firmware, and once using the Google compiler for the brewblox-particle test suite.
To compile proto files, use invoke build.proto. This is only required if the submodule commit for brewblox-proto was changed.
Build targets
The Spark firmware is built for six targets, using three separate toolchains.
| Target | Platform | Toolchain |
|---|---|---|
| Photon | Spark 2 | Particle |
| P1 | Spark 3 | Particle |
| ESP32 | Spark 4 | ESP-IDF |
| AMD64 | Simulator | Generic |
| ARM32 | Simulator | Generic |
| ARM64 | Simulator | Generic |
Deployment and releases
The CI build collects the artifacts for all build targets, and uploads a tarball to Azure file storage along with a firmware.ini file detailing build dates and version hashes. This is done for every non-PR CI build.
For the firmware build to be released to users, the Spark service must include the new firmware in its Docker image.
This is done by downloading and committing the new firmware.ini file, and then triggering a CI build.
During the Spark service CI build, the firmware tarball that matches the version hash in firmware.ini is downloaded from Azure storage, and included in the resulting Docker image.
License
Unless stated elsewhere, file headers or otherwise, all files herein are licensed under an GPLv3 license. For more information, please read the LICENSE file.
Contributing
Contributions to our firmware are very welcome. To avoid wasted efforts, we recommend first discussing proposed changes on the community forum or Discord.
Please send pull requests against the develop branch. We can only accept your pull request if you have signed our Contributor License Agreement (CLA).